Rebillia MCP Server

Model Context Protocol (MCP) server for the Rebillia Public API. It exposes tools to call the API and resources with API documentation so AI assistants can manage customers, products, rate plans, and understand the API.

Features

• Tools – Call Rebillia endpoints from your MCP client (e.g. Cursor, Claude Desktop):
  • Customers (22 tools) – List, get, create, update, delete; invoices (including unpaid), subscriptions, logs; addresses and payment methods; charges/credits
  • Products (8 tools) – List, get, create, update, delete; update status; link/unlink external products
  • Product rate plans (7 tools) – List by product, get, create, update, delete; update status; sync
  • Product rate plan charges (5 tools) – List by product rate plan, get, create, update, delete (with chargeType, chargeModel, billingPeriod, billingTiming enums and chargeTier array)
  • Subscriptions (19 tools) – List, get, create, update, delete; status; next bill, upcoming charges, invoices, logs, external invoices; subscription rate plans and rate plan charges (add/update/remove)
  • Invoices (8 tools) – List, get, create, update, delete; charge (card/online with paymentType), charge_external (offline), void
• Transactions (4 tools) – List (customerId, invoiceId, status, type, dateFrom/dateTo, companyGatewayId, orderBy/sortBy, pagination), get, refund (amount in cents), void (before settlement only)
  • Bill runs (4 tools) – List (filter by completed/pending/error), get, update (newDateTime, ISO 8601; pending only), get bill run invoices
• Gateways (9 tools) – List global gateways (discover gblGatewayId and required setting keys), list company gateways, get, create, update, delete, test gateway, get client token, create setup intent
• Currencies (7 tools) – List, get, create, update, delete, get/set default currency
• Integrations (8 tools) – List, get config, get/list by key; external invoices, products, order statuses
• Shipping (2 tools) – List shipping services, calculate shipping
• Filters (4 tools) – List filters (section required), create filter, list filter fields, remove filter
• Documentation (1 tool) – get_api_docs returns overview or other API docs as markdown (no external fetch)
• Resources – API docs via MCP resources (rebillia://docs/*): overview, models, subscription-statuses, charge-types, gateways. Country list at rebillia://globals/countries (id, code, name) for address tools. Global gateways at rebillia://globals/gateways (gblGatewayId, requiredFields) for gateway creation. All docs are self-contained; use these or the tool instead of fetching external URLs.
• Types – TypeScript types aligned with the Rebillia Public API response shapes

Requirements

• Node.js 18+
• A Rebillia API key (see below)

Getting Your API Key

1. Go to Rebillia setup / welcome.
2. Select a plan and continue.
3. Sign up (create an account) or log in if you already have a Rebillia account.
4. After you’re in your company, open the dashboard.
5. In the dashboard, copy your API Token and use it as REBILLIA_API_KEY in your environment or MCP client config.

Setup

1. Clone and install

   cd /path/to/rebillia-mcp-server
   npm install
   

2. Configure environment

   Copy the example env file and set your API key and optional base URL:

   cp .env.example .env
   

   Edit .env:

   REBILLIA_API_KEY=your_api_key_here
   REBILLIA_API_URL=https://api.rebillia.com/v1
   

   • REBILLIA_API_KEY – Required. Used as X-AUTH-TOKEN for all requests.
   • REBILLIA_API_URL – Optional. Defaults to https://api.rebillia.com/v1 (include /v1 for the Public API).

3. Build

   npm run build
   

Usage

Running the server

Development (no build step):

npm run dev

Production:

npm run build
npm start

Or run the binary:

./node_modules/.bin/rebillia-mcp-server

The server uses stdio transport: it reads JSON-RPC from stdin and writes responses to stdout. MCP clients connect to it as a subprocess.

Configuring Claude Desktop

1. Build the server (if you haven’t already):

   npm run build
   

2. Open the Claude Desktop MCP config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Add the Rebillia server under mcpServers:

   {
     "mcpServers": {
       "rebillia": {
         "command": "npx",
         "args": ["@rhinosaas/rebillia-mcp-server"],
         "env": {
           "REBILLIA_API_KEY": "YOUR_API_KEY",
           "REBILLIA_API_URL": "https://api.rebillia.com/v1"
         }
       }
     }
   }
   

4. Restart Claude Desktop. The Rebillia tools and resources (including get_api_docs) will appear. You can ask Claude to use the Rebillia API or to “get the API docs” for overview information.

Configuring Cursor

1. Build the server:

   npm run build
   

2. Open Cursor MCP settings:

   • Settings → Cursor Settings → MCP, or
   • Open the MCP config file directly:
     • macOS/Linux: ~/.cursor/rebillia-mcp-server.json or project-level .cursor/mcp.json

• Windows: %USERPROFILE%\.cursor\rebillia-mcp-server.json

3. Add the Rebillia server in the MCP config. Example:

   {
     "mcpServers": {
       "rebillia": {
         "command": "npx",
         "args": ["@rhinosaas/rebillia-mcp-server"],
         "env": {
           "REBILLIA_API_KEY": "your_api_key_here",
           "REBILLIA_API_URL": "https://api.rebillia.com/v1"
         }
       }
     }
   }
   

4. Restart Cursor or reload the MCP servers. Rebillia tools and resources will be available in the AI chat (e.g. “List customers”, “Get API docs”).

Tools

Responses are JSON from the Rebillia Public API (paginated for list endpoints, single object for get).

Customers (22 tools)

Tool	Description
list_customers	List customers (pageNo, itemPerPage, query, status, sortBy, orderBy, include, filterId).
get_customer	Get customer by ID (optional include: addressbook, paymentmethod, lastInvoice, subscriptions, unpaidInvoices, externalCustomers).
create_customer	Create customer (firstName, lastName, email, optional fields).
update_customer	Update customer by ID.
delete_customer	Delete customer by ID.
get_customer_invoices	Get invoices for a customer (optional: status = authorized|posted|canceled|partialPaid|paid|voided|refund|partialRefund, dateFrom, dateTo, subscriptionId, include, pageNo, itemPerPage).
get_customer_unpaid_invoices	Get unpaid invoices for a customer (GET /customers/{customerId}/invoices/unpaid) with optional pageNo, itemPerPage.
get_customer_subscriptions	Get subscriptions for a customer.
get_customer_logs	Get logs for a customer.
list_customer_addresses	List address book entries for a customer (pageNo, itemPerPage).
get_customer_address	Get address by ID.
create_customer_address	Create address (name, contactName, street1, city, state, zip, countryCode (ISO 3166-1 alpha-2), type, …).
update_customer_address	Update address by ID (partial update). Required: customerId, addressId. Optional: any address field (e.g. street1, city, state, zip, countryCode, name, contactName, street2, company, contactEmail, contactPhone, type (residential
delete_customer_address	Delete address by ID.
list_customer_payment_methods	List payment methods for a customer (pageNo, itemPerPage).
get_customer_payment_method	Get payment method by ID.
create_customer_payment_method	Create payment method (gateway-agnostic). Required: companyGatewayId, type, paymentMethodNonce, billingAddress (countryCode, …). Get client credential via get_client_token; use your payment UI to produce paymentMethodNonce. No raw card data or gateway-specific fields.
update_customer_payment_method	Update payment method billing address (gateway-agnostic). Required: customerId, paymentMethodId, billingAddress (countryCode, …). No payment or gateway-specific fields.
delete_customer_payment_method	Delete payment method by ID.
list_customer_charges_credits	List charges/credits (optional status, type).
create_customer_charge_credit	Create charge/credit (amount in cents, description, type, companyCurrencyId, category, …).
delete_customer_charge_credit	Delete charge/credit by ID.

Products (8 tools)

Tool	Description
list_products	List products (include: productRateplan, productRateplanCharge, chargeTier; status: published|draft|archived|disabled; name; category: baseProducts|addOn|bundleProduct|miscellaneous|service; orderBy, sortBy, itemPerPage, pageNo).
get_product	Get product by ID.
create_product	Create product (name, category, optional description, sku).
update_product	Update product by ID.
delete_product	Delete product by ID (cascades to product rate plans).
update_product_status	Update status (published, archived, disabled).
link_external_product	Link external product (productId, companyIntegrationId, external productId, settings).
unlink_external_product	Unlink external product by ID.

Product rate plans (7 tools)

Tool	Description
list_product_rate_plans	List product rate plans for a product (GET /products/{productId}/product-rateplans).
get_product_rate_plan	Get product rate plan by ID.
create_product_rate_plan	Create product rate plan (productId, name, type: contract|ongoing|prepaid).
update_product_rate_plan	Update product rate plan by ID.
delete_product_rate_plan	Delete product rate plan by ID.
update_product_rate_plan_status	Update status (published, archived, disabled, discontinue).
sync_product_rate_plan	Sync product rate plan (POST …/sync).

Product rate plan charges (5 tools)

Tool	Description
list_product_rate_plan_charges	List product rate plan charges for a product rate plan (GET …/product-rateplan-charges).
get_product_rate_plan_charge	Get product rate plan charge by ID.
create_product_rate_plan_charge	Create product rate plan charge (ratePlanId, name, chargeType, chargeModel, billCycleType, category, chargeTier array, taxable, weight, endDateCondition, …). Enums: chargeType (oneTime, recurring, usage), chargeModel (flatFeePricing, perUnitPricing, tieredPricing, volumePricing), billingPeriod (day, week, month, year), billingTiming (inAdvance, inArrears).
update_product_rate_plan_charge	Update product rate plan charge by ID.
delete_product_rate_plan_charge	Delete product rate plan charge by ID.

Subscriptions (19 tools)

Tool	Description
list_subscriptions	List subscriptions (include, query, orderBy, sortBy, filterId, status, customerId, companyGatewayId, dateFrom, dateTo, itemPerPage, pageNo). status supports: active, paused, requestPayment, archived. dateFrom/dateTo are YYYY-MM-DD createdAt-range filters.
get_subscription	Get subscription by ID.
create_subscription	Create subscription from product rate plan (productRatePlanId, customerId, customerPaymentMethodId, billingAddressId, effectiveStartDate).
update_subscription	Update subscription by ID.
delete_subscription	Delete subscription by ID.
update_subscription_status	Update status (e.g. archived).
get_subscription_upcoming_charges	Upcoming charges.
get_subscription_invoices	Invoices for subscription.
get_subscription_logs	Logs for subscription.
get_subscription_external_invoices	External invoices.
list_subscription_rate_plans	Rate plans on subscription (optional status: active|pause|cancel|archived; type: ongoing|prepaid|contract, case-insensitive).
get_subscription_rate_plan	Get rate plan by ID.
add_subscription_rate_plan	Add rate plan to subscription.
update_subscription_rate_plan	Update rate plan (effectiveStartDate, etc.).
remove_subscription_rate_plan	Remove rate plan from subscription.
get_subscription_rate_plan_charge	Get rate plan charge by ID.
add_subscription_rate_plan_charge	Add charge to rate plan. Required: subscriptionId, ratePlanId, quantity, name, category (physical|digital), chargeModel (flatFeePricing|perUnitPricing|tieredPricing|volumePricing), billCycleType, chargeTier (array: currency, price required; optional startingUnit, endingUnit, priceFormat, tier), chargeType (oneTime|recurring|usage), endDateCondition (subscriptionEnd|fixedPeriod), taxable (boolean), weight. When chargeType is recurring, billingPeriodAlignment and specificBillingPeriod are also required.
update_subscription_rate_plan_charge	Update rate plan charge. Required: subscriptionId, chargeId, quantity, name, chargeModel, billCycleType, chargeTier (currency, price), chargeType, endDateCondition, taxable, weight. When chargeType is recurring, billingPeriodAlignment required.
remove_subscription_rate_plan_charge	Remove charge from rate plan.

Invoices (8 tools)

Tool	Description
list_invoices	List invoices (include, status, query, orderBy, sortBy, filterId, itemPerPage, pageNo).
get_invoice	Get invoice by ID.
create_invoice	Create invoice. Required: companyCurrencyId, companyGatewayId, customerId, paymentMethodId, detail. Optional billingAddress/shippingAddress use countryCode (ISO 3166-1 alpha-2). Amount can be '41.00' (dollars) or 4100 (cents); tool always sends cents to publicAPI.
update_invoice	Update invoice (only posted/requestPayment).
delete_invoice	Delete invoice by ID.
charge_invoice	Charge invoice (card/online). Required: invoiceId, amount (cents), paymentType (e.g. thirdPartyPaymentProvider).
charge_invoice_external	Charge via offline (cash/check/wire). Required: invoiceId, amount (cents).
void_invoice	Void invoice (irreversible).

Transactions (4 tools)

Tool	Description
list_transactions	List transactions (customerId, invoiceId, status, type, dateFrom, dateTo, companyGatewayId, orderBy, sortBy, itemPerPage, pageNo). status: settled|authorized|declined|error|voided|requiresPaymentMethod|awaitingForSettlement|authorizeAndHold. type: sale|refund.
get_transaction	Get transaction by ID.
refund_transaction	Refund transaction. Required: transactionId, amount (in cents, e.g. 250 = $2.50).
void_transaction	Void transaction (before settlement only).

Bill runs (4 tools)

Tool	Description
list_bill_runs	List bill runs. Optional: include (e.g. invoice), query (completed/pending/error), orderBy, sortBy, itemPerPage, pageNo.
get_bill_run	Get bill run by ID.
update_bill_run	Update bill run schedule. Required: billRunId, newDateTime (ISO 8601, e.g. 2026-02-26T20:05:00Z). Note: this tool only works on bill runs with status pending. Calls against completed or error runs will fail.
get_bill_run_invoices	Get invoices for a bill run. Optional: pageNo, itemPerPage.

Gateways (9 tools)

Tool	Description
list_global_gateways	List available global gateway types (e.g. Stripe, Braintree). Returns gblGatewayId, name, keyName, requiredFields (setting keys), and fieldDetails. Call this before create_gateway to discover valid gateway IDs and which keys to pass in setting.
list_gateways	List company gateways.
get_gateway	Get gateway by ID.
create_gateway	Create gateway. Required: gblGatewayId (from list_global_gateways), setting (object with keys from that gateway’s requiredFields). Optional: displayName, card, paymentMethod. Use list_global_gateways first to get gblGatewayId and required credential field names.
update_gateway	Update gateway by ID.
delete_gateway	Delete gateway by ID.
test_gateway	Test gateway connection.
get_client_token	Get the gateway client credential to initialize your payment integration and produce a paymentMethodNonce for create_customer_payment_method. Gateway-agnostic. Required: gatewayId. Optional: customerId; required for PayFabric, optional for others.
create_setup_intent	Create/retrieve a setup intent via /gateways/{companyGatewayId}/customers/{customerId}/setup_intent. Use setupIntent.id as paymentMethodNonce for create_customer_payment_method (gateway-agnostic payment flow).

Gateway creation example flow: (1) Call list_global_gateways (no args). (2) Pick a gateway (e.g. Stripe, Braintree) and note its gblGatewayId and requiredFields. (3) Build a setting object with those keys and your credential values. (4) Call create_gateway with that gblGatewayId and setting. See rebillia://docs/gateways or get_api_docs with doc: "gateways" for full details.

Currencies (7 tools)

Tool	Description
list_currencies	List company currencies.
get_currency	Get currency by ID.
create_currency	Create company currency.
update_currency	Update currency by ID.
delete_currency	Delete currency by ID.
get_default_currency	Get default company currency.
set_default_currency	Set default currency by ID.

Integrations (8 tools)

Tool	Description
list_integrations	List company integrations.
get_integration_config	Get integration config by ID.
get_integration_by_key	Get integration by key.
list_integrations_by_key	List integrations by key.
list_external_invoices	List external invoices.
list_external_products	List external products (productName required).
get_external_product	Get external product by ID.
list_order_statuses	List order statuses.

Shipping (2 tools)

Tool	Description
list_shipping_services	List shipping services.
calculate_shipping	Calculate shipping (companyCurrencyId, fromZip, fromCountry, zip, country, weight, orderAmount, etc.).

Filters (4 tools)

Tool	Description
list_filters	List company filters. Required: section (e.g. subscriptions, invoices, customers, products, orders, billRuns).
create_filter	Create filter (section, displayName, rules).
list_filter_fields	List filter fields for a section.
remove_filter	Delete a company filter by ID (DELETE /companies/filters/{filterId}).

Documentation (1 tool)

Tool	Description
get_api_docs	Get Rebillia API documentation as markdown. Default: overview (base URLs, auth, pagination, dates, amounts). Optional: doc = overview | models | subscription-statuses | charge-types | gateways. Use this so Claude can read docs without fetching external URLs.

Resources

API documentation is exposed as MCP resources under rebillia://docs/*. Use resources/list then resources/read with the URI, or call the get_api_docs tool. All docs are self-contained; do not fetch external URLs.

URI	Description
rebillia://docs/overview	Overview documentation – base URLs, auth, pagination, date format, amount handling (read this first)
rebillia://docs/models	Domain model hierarchy and relationships
rebillia://docs/subscription-statuses	Subscription statuses: active, paused, archived, requestPayment
rebillia://docs/charge-types	chargeType, chargeModel, billingPeriod, billingTiming enums
rebillia://docs/gateways	Gateway creation flow: use list_global_gateways to discover gblGatewayId and requiredFields, then build setting and call create_gateway
rebillia://globals/gateways	Global gateways list (when client provided): gblGatewayId, name, keyName, requiredFields, fieldDetails – use with create_gateway

Project structure

src/
├── index.ts              # MCP server entry, tools + resources handlers
├── client.ts             # HTTP client for Rebillia API (X-AUTH-TOKEN)
├── types.ts              # Rebillia API types (customers, invoices, etc.)
├── services/             # API call layer (used by tools)
│   ├── customerServices.ts
│   ├── productServices.ts
│   ├── productRatePlanServices.ts
│   ├── productRatePlanChargeServices.ts
│   ├── subscriptionServices.ts
│   ├── invoiceServices.ts
│   ├── transactionServices.ts
│   ├── billRunServices.ts
│   ├── gatewayServices.ts
│   ├── globalGatewayService.ts
│   ├── countryResolverService.ts
│   ├── currencyServices.ts
│   ├── integrationServices.ts
│   ├── shippingServices.ts
│   └── filterServices.ts
├── tools/
│   ├── index.ts          # Tool registry, getToolDefinitions(), executeTool()
│   ├── types.ts          # Tool definition and handler types
│   ├── customers/        # Customer tools (22)
│   ├── products/         # Product tools (8)
│   ├── product_rate_plans/         # Product rate plan tools (7)
│   ├── product_rate_plan_charges/  # Product rate plan charge tools (5)
│   ├── subscriptions/    # Subscription tools (19)
│   ├── invoices/         # Invoice tools (8)
│   ├── transactions/     # Transaction tools (4)
│   ├── bill_runs/        # Bill run tools (4)
│   ├── gateways/         # Gateway tools (9)
│   ├── currencies/       # Currency tools (7)
│   ├── integrations/     # Integration tools (8)
│   ├── shipping/         # Shipping tools (2)
│   ├── filters/          # Filter tools (4)
│   └── docs/             # get_api_docs (1)
├── resources/
│   ├── index.ts          # listResources(), readResource()
│   └── api-docs.ts       # registerResources(), doc resources, getDocContent()
├── prompts/              # (reserved for MCP prompts)
└── types/
    └── addressInput.ts

Scripts

Script	Command	Description
build	npm run build	Compile TypeScript to dist/
start	npm start	Run node dist/index.js
dev	npm run dev	Run with tsx (no build)
test	npm test	Run Vitest
test:run	npm run test:run	Run tests once (non-watch mode)

License

MIT