Zuora MCP Server

A Model Context Protocol (MCP) server that enables Claude to interact with Zuora's billing platform. Query accounts, invoices, subscriptions, payments, and execute ZOQL queries directly from Claude Code.

Quick Start

Run one command — no cloning, no building:

npx @armor/zuora-mcp setup

The setup wizard will:

1. Ask for your Zuora OAuth credentials
2. Let you choose your Zuora environment (sandbox, production, EU)
3. Auto-configure Claude Code and/or Claude Desktop

Then restart Claude Code and the Zuora tools are ready.

Prerequisites

• Node.js 20+
• Zuora OAuth credentials (create at Zuora Admin > Settings > Administration > OAuth Clients)

Manual Configuration (Alternative)

If you prefer to configure manually, add to ~/.claude/.mcp.json:

{
  "mcpServers": {
    "zuora": {
      "command": "npx",
      "args": ["-y", "@armor/zuora-mcp"],
      "env": {
        "ZUORA_CLIENT_ID": "your-client-id",
        "ZUORA_CLIENT_SECRET": "your-client-secret",
        "ZUORA_BASE_URL": "https://rest.apisandbox.zuora.com"
      }
    }
  }
}

Install from Source

git clone [email protected]:armor/zuora-mcp.git
cd zuora-mcp
npm install
npm run build

When installing from source, point to the built file in your MCP config:

{
  "mcpServers": {
    "zuora": {
      "command": "node",
      "args": ["/path/to/zuora-mcp/dist/index.js"],
      "env": {
        "ZUORA_CLIENT_ID": "your-client-id",
        "ZUORA_CLIENT_SECRET": "your-client-secret",
        "ZUORA_BASE_URL": "https://rest.apisandbox.zuora.com"
      }
    }
  }
}

Configuration

Required environment variables:

| Variable | Description | |----------|-------------| | ZUORA_CLIENT_ID | OAuth2 client ID | | ZUORA_CLIENT_SECRET | OAuth2 client secret | | ZUORA_BASE_URL | One of the Zuora base URLs (see below) |

Optional variables:

| Variable | Description | |----------|-------------| | DEBUG | Set to true for verbose logging |

Zuora Base URLs

| Environment | URL | |-------------|-----| | US Production | https://rest.zuora.com | | US Sandbox | https://rest.apisandbox.zuora.com | | EU Production | https://rest.eu.zuora.com | | EU Sandbox | https://rest.sandbox.eu.zuora.com |

Getting Zuora OAuth Credentials

1. Log into Zuora (production or sandbox)
2. Navigate to Settings > Administration > Manage Users
3. Select your user or create a service account
4. Go to OAuth Clients tab and create a new client
5. Copy the Client ID and Client Secret (secret is shown only once)

Available Tools

Account Tools

| Tool | Description | |------|-------------| | get_account | Get account details by key (ID or account number) | | get_account_summary | Get comprehensive account summary with balances, subscriptions, invoices, and payments |

Invoice Tools

| Tool | Description | |------|-------------| | get_invoice | Get invoice details including line items | | list_invoices | List invoices for an account with pagination |

Subscription Tools

| Tool | Description | |------|-------------| | get_subscription | Get subscription details with rate plans and charges | | list_subscriptions | List all subscriptions for an account |

Payment Tools

| Tool | Description | |------|-------------| | get_payment | Get payment details | | list_payments | List payments with optional account filter and pagination |

ZOQL Query Tools

| Tool | Description | |------|-------------| | execute_zoql_query | Execute a ZOQL query for ad-hoc data retrieval | | continue_zoql_query | Continue paginated ZOQL results using queryLocator |

Product Catalog

| Tool | Description | |------|-------------| | list_products | List products with rate plans and pricing |

Upgrading

npm update -g @armor/zuora-mcp

Development

npm run dev        # Run with tsx (no build required)
npm run build      # Build TypeScript to dist/
npm run lint       # Run ESLint
npm run typecheck  # Type check without building
npm test           # Build and run tests
npm run clean      # Remove dist/

Debug Mode

Set DEBUG=true to enable verbose logging to stderr:

DEBUG=true npm start

Debug output goes to stderr to avoid corrupting the stdio JSON-RPC transport.

Release Process

This project uses semantic-release with branch-based publishing:

| Branch | npm Tag | Description | |--------|---------|-------------| | dev | alpha | Development pre-releases | | stage | beta | Staging pre-releases | | main | latest | Production releases |

Merging to any of these branches triggers the CD pipeline which:

1. Runs lint, typecheck, build, and tests
2. Determines the next version from commit messages
3. Creates a GitHub release with notes
4. Publishes to npm with the appropriate tag

Commit Convention

Follow conventional commits for automatic version bumps:

| Prefix | Version Bump | |--------|--------------| | feat: | Minor (1.x.0) | | fix: | Patch (1.0.x) | | breaking: | Major (x.0.0) |

Architecture

src/
├── cli.ts              # CLI entry point (bin): server, setup, --help, --version
├── setup.ts            # Interactive setup wizard (zero external deps)
├── index.ts            # MCP server bootstrap (exports startServer)
├── config.ts           # Zod-validated environment configuration
├── token-manager.ts    # OAuth2 token lifecycle (refresh, coalescing)
├── zuora-client.ts     # Zuora REST API client with resilience
├── tools.ts            # Tool definitions, Zod schemas, handlers
├── zoql-helpers.ts     # ZOQL query composition utilities
├── resources.ts        # MCP resources (data model, ZOQL guides)
├── prompts.ts          # MCP prompts (finance workflow templates)
└── types.ts            # TypeScript interfaces

Authentication

Uses OAuth 2.0 Client Credentials flow:

• Tokens are stored in memory only (not persisted)
• Proactive refresh 60 seconds before expiry
• Promise coalescing prevents duplicate refresh requests under concurrency
• Automatic 401 retry with token refresh

Resilience

• Exponential backoff with jitter on 429/502/503/504
• Idempotent methods (GET, PUT, DELETE) retry on transport failures
• POST requests are NOT retried on HTTP errors (financial safety)
• 20-second request timeout with AbortController

Security

• All inputs validated with Zod schemas
• Sensitive fields (card numbers, bank accounts) redacted from debug logs
• Bearer tokens scrubbed from error messages
• OAuth credentials never logged
• Base URL validated against known Zuora endpoints at startup

Version History

v1.0.0

• Initial release with 11 read-only tools
• OAuth 2.0 authentication with token lifecycle management
• Account, invoice, subscription, payment, and ZOQL query support
• Product catalog access
• Resilient HTTP client with retry and backoff