Recurly MCP Server — Headless Recurly with Claude

A mock MCP (Model Context Protocol) server that exposes 98 Recurly subscription management tools to Claude Desktop. All tools return realistic hardcoded data for StreamAI, a fictional mid-market streaming merchant.

StreamAI at a glance

• MRR: $2,142,000
• Active subscribers: 87,420
• Plans: Starter ($9.99/mo), Pro ($24.99/mo), Enterprise ($149/mo)
• Key problem: Cohort 3 (month 3–4) churning at 18% vs 11% baseline
• Active campaign: Q1 cancel-save with 30% discount variant leading at 34% retention

Quick start

# Install dependencies
npm install

# Build
npm run build

# Test that the server starts (ctrl+c to stop)
npm start

Configure Claude Desktop

Add the following to your Claude Desktop config file:

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

{
  "mcpServers": {
    "recurly": {
      "command": "/Users/jbluhm/.volta/bin/node",
      "args": ["/Users/jbluhm/Desktop/mcp-future/dist/index.js"]
    }
  }
}

Note: The full path to node is required because Claude Desktop doesn't inherit your shell's PATH (e.g., Volta, nvm). Run which node in your terminal to find yours.

Restart Claude Desktop after saving the config. You should see "recurly" appear in the MCP server list.

Tool domains (98 total)

| Domain | Tools | Examples | |--------|-------|---------| | A — Subscriber & Billing | 20 | get_account, cancel_subscription, create_coupon | | B — Revenue Intelligence | 18 | get_merchant_health_summary, run_pricing_simulation, forecast_revenue | | C — Retention & Campaigns | 16 | create_campaign, get_cancel_save_performance, get_win_back_candidates | | D — Agentic Workflows | 12 | create_agent_task, get_hitl_pending_approvals, simulate_agent_run | | E — Next-Gen Billing | 14 | ingest_usage_event, create_micro_access_pass, get_billing_model_recommendation | | F — Platform & Integrations | 10 | get_integration_status, process_agent_checkout, get_audit_log | | G — Agentic Commerce (B2A) | 8 | get_agent_purchase_negotiations, get_subscriber_self_service_actions |

Example prompts to try

Once connected in Claude Desktop:

• "How is StreamAI doing? Give me the full health summary."
• "Show me the high-risk Pro subscribers in month 3–4 and what we can do about them."
• "What would happen if we raised the Pro price to $27.99 for new subscribers?"
• "Create a cancel-save campaign for the cohort 3 churn problem."
• "What are the pending approvals from the retention agent?"
• "Show me Jane Doe's account and tell me if we should intervene."

Development

# Watch mode (recompiles on save)
npm run dev

Project structure

src/
  index.ts              # Entry point — creates server, registers domains, connects stdio
  mock-data.ts           # Shared StreamAI constants (merchant, accounts, plans, benchmarks)
  helpers.ts             # textResult(), makeActionLog(), wrapDryRun()
  domains/
    a-subscriber-billing.ts
    b-revenue-intelligence.ts
    c-retention-campaigns.ts
    d-agentic-workflows.ts
    e-next-gen-billing.ts
    f-platform-integrations.ts
    g-agentic-commerce.ts