recurly-mcp

A read-only MCP (Model Context Protocol) server that exposes the Recurly v2021-02-25 API to LLM clients. Works with any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Cline, Codex CLI, Continue.dev, etc.).

Thirty resource-grouped tools cover every read (GET) endpoint Recurly exposes — accounts, subscriptions, invoices, transactions, line items, plans, coupons, items, usage, exports, external products/subscriptions, and the rest — plus a generic recurly_request escape hatch for anything not directly modeled.

This server is read-only by construction: the HTTP client only ever issues GET. There is no code path that can create, update, or delete Recurly data — including via the escape hatch.

Unofficial. Not affiliated with or endorsed by Recurly.

Install

Claude Code (one-liner)

claude mcp add recurly --scope user \
  --env RECURLY_API_KEY=YOUR_PRIVATE_API_KEY \
  -- npx -y recurly-mcp

Restart Claude Code and the recurly_* tools become available.

Run the binary directly (optional)

The server is normally spawned by your MCP client over stdio. To test it stand-alone:

RECURLY_API_KEY=your_private_api_key npx recurly-mcp

It will wait for JSON-RPC messages on stdin. Useful for debugging the install only.

Configuration

All configuration is via environment variables.

| Var | Required | Default | Purpose | |---|---|---|---| | RECURLY_API_KEY | yes | — | Private API key. Sent as the HTTP Basic auth username (empty password). | | RECURLY_REGION | no | us | us or eu — selects the API host. | | RECURLY_HOST | no | https://v3.recurly.com | Override the API origin entirely (local mocks, proxies). Overrides RECURLY_REGION. | | RECURLY_API_VERSION | no | v2021-02-25 | Recurly API version sent in the Accept header. The tool paths/params here are modeled on v2021-02-25. | | RECURLY_TIMEOUT_MS | no | 15000 | Per-request timeout. | | RECURLY_MAX_RETRIES | no | 2 | Retries on 429 and 5xx (honors Retry-After, equal-jitter backoff). |

Get a private API key from the Recurly dashboard → Integrations → API Credentials. Use a key scoped to read-only access where possible — this server never writes, but defense in depth is good.

MCP client config

The MCP entry below is the same for every MCP client — only the config file location differs.

{
  "mcpServers": {
    "recurly": {
      "command": "npx",
      "args": ["-y", "recurly-mcp"],
      "env": {
        "RECURLY_API_KEY": "your_private_api_key_here"
      }
    }
  }
}

Where to put it, by client:

| Client | Location | |---|---| | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Code | ~/.claude.json — or use claude mcp add recurly --scope user --env RECURLY_API_KEY=… -- npx -y recurly-mcp | | Cursor | .cursor/mcp.json (per-project) or ~/.cursor/mcp.json (user-wide) | | Cline (VS Code) | VS Code Settings → Cline → MCP servers (UI), or cline_mcp_settings.json | | Codex CLI | ~/.codex/config.json under mcpServers | | Continue.dev | .continue/config.json under experimental.modelContextProtocolServers |

For the EU data region, add "RECURLY_REGION": "eu" to env.

Tools

Every action is read-only. Each tool takes an action discriminator plus the parameters for that action.

| Tool | Actions | |---|---| | recurly_sites | list, get | | recurly_accounts | list, get, get_balance, get_acquisition, list_acquisitions, list_child_accounts, list_notes, get_note, list_entitlements | | recurly_billing_info | get, list, get_one | | recurly_shipping_addresses | list, get | | recurly_coupons | list, get, list_unique_coupon_codes, get_unique_coupon_code | | recurly_coupon_redemptions | list_for_account, list_active_for_account, get_for_account, list_for_invoice, list_for_subscription, get_for_subscription | | recurly_credit_payments | list, get, list_for_account | | recurly_invoices | list, get, get_pdf, list_line_items, list_related, list_for_account | | recurly_line_items | list, get, list_for_account | | recurly_subscriptions | list, get, get_change, get_preview_renewal, list_invoices, list_line_items, list_for_account | | recurly_transactions | list, get, list_for_account | | recurly_custom_field_definitions | list, get | | recurly_items | list, get | | recurly_measured_units | list, get | | recurly_plans | list, get, list_add_ons, get_add_on | | recurly_add_ons | list, get | | recurly_shipping_methods | list, get | | recurly_usage | list, get | | recurly_export | get_dates, get_files | | recurly_dunning_campaigns | list, get | | recurly_invoice_templates | list, get, list_accounts | | recurly_external_products | list, get, list_references, get_reference | | recurly_external_subscriptions | list, get, list_invoices, list_payment_phases, get_payment_phase, list_for_account | | recurly_external_invoices | list, get, list_for_account | | recurly_external_accounts | list, get | | recurly_general_ledger_accounts | list, get | | recurly_performance_obligations | list, get | | recurly_price_segments | list, get | | recurly_business_entities | list, get, list_invoices | | recurly_gift_cards | list, get | | recurly_request | Escape hatch — a raw GET to any Recurly API path. |

Tools return raw Recurly JSON payloads with no field-stripping. list actions add a _pagination metadata object so the model can iterate pages.

IDs and codes

Most ID parameters accept either the opaque Recurly object ID (e.g. e28zov4fw0v2) or a prefixed human key:

• accounts/plans/items/coupons/…: code-<your_code>
• sites: subdomain-<name>
• invoices: number-<invoice_number>
• subscriptions/transactions: uuid-<uuid>

Values are URL-encoded before interpolation, so codes containing special characters work, and path-traversal segments are rejected.

Pagination

Recurly uses cursor-based pagination. list actions accept limit (1–200), order (asc/desc), sort, cursor, ids, begin_time, end_time, plus resource-specific filters (state, type, etc.). Responses include Recurly's native has_more/next, and this server adds a _pagination hint:

{ "object": "list", "has_more": true, "next": "/accounts?cursor=…", "data": [ … ],
  "_pagination": { "has_more": true, "next_cursor": "…" } }

Pass _pagination.next_cursor back as cursor to fetch the next page.

Invoice PDFs

recurly_invoices get_pdf returns the PDF as a base64 wrapper rather than a mangled string:

{ "object": "binary_file", "content_type": "application/pdf", "encoding": "base64", "byte_length": 12345, "data": "JVBERi0…" }

Coverage notes

• Write operations are intentionally not modeled. This is a read-only server; the client cannot issue anything but GET.
• Filters beyond the common set are reachable via recurly_request ({ "path": "/...", "query": { … } }) if a specific list endpoint accepts a parameter not modeled on its typed tool.

Development

npm install
npm test                 # vitest, 154 tests
npm run typecheck
npm run lint
npm run build            # emits dist/
npm run validate         # spawns the built server, checks tool schemas (expects 31 tools)
npm run dev              # tsx src/bin.ts (for local stdio testing)

Contributing

Issues and pull requests welcome at https://github.com/francktrouillez/recurly-mcp/issues.

Bug reports are most useful with: the tool and action you called, the params (with secrets redacted), and the response.

License

MIT