Billforward MCP Server 🚀

A high-performance Model Context Protocol (MCP) server for integrating Billforward's robust billing and subscription management API with LLMs.

🛠 Features

• Entity Discovery: Quickly list and inspect Accounts and Subscriptions.

• Protocol Purity: Zero log leakage to stdout, ensuring 100% reliable JSON-RPC communication.

• Security First: Built-in BILLFORWARD_READ_ONLY=true (default) mode to protect your data with instructional LLM error rejections.

• Modern SDK: Uses the latest @modelcontextprotocol/sdk signatures (registerTool).

• Fully Testable: Includes protocol compliance and unit tests via Vitest.

Related MCP server: QuickFile MCP Server

🔑 How to Get Your API Token

You need an API token to allow the MCP server to communicate with Billforward.

1. Log in to your Billforward environment.

2. Navigate to Setup > Personal > API Keys.

3. Create a new token and copy it.

Quick Links:

• 🟢 Sandbox Environment API Keys

• 🚀 Production Environment API Keys

⚙️ Configuration

To run this server with npx (local or published):

{
  "mcpServers": {
    "billforward": {
      "command": "npx",
      "args": [
        "-y",
        "billforward-mcp"
      ],
      "env": {
        "BILLFORWARD_SANDBOX_ACCESS_TOKEN": "your_sandbox_token",
        "BILLFORWARD_PRODUCTION_ACCESS_TOKEN": "your_production_token",
        "BILLFORWARD_READ_ONLY": "true"
      }
    }
  }
}

Configure whichever environments you have — one or both. When both are set, the LLM must pass environment: "sandbox" or "production" on each call; with only one set it is used automatically.

Advanced Environment Variables

The server behaves differently depending on these configurations:

🧰 Available Tools

� Search & Insights

• search: Parallelized unified search across Accounts, Subscriptions, and Invoices using email, ID, or keyword.

• get-customer-summary: 360-degree dashboard of a customer (profile, subs, recent invoices, dunning status).

• get-metadata-schema: Analyzes metadata keys in use across Accounts, Subscriptions, and Invoices to help filter queries.

�📖 Guidance

• help: Get an overview of available entities and usage patterns.

• get-me: Validate your connection and view profile metadata.

👥 Accounts

• list-accounts: Fetch a paginated list of accounts (limit, offset, metadata, created_after/created_before).

• get-account: Retrieve full details for a specific UUID.

• get-account-by-email: Find an account quickly by its exact email address.

📝 Subscriptions

• list-subscriptions: Fetch a paginated list of subscriptions (limit, offset, period_start_after/period_start_before — Billforward has no native filter on subscription creation date, so this filters by billing period start instead).

• get-subscription: Retrieve full details for a specific UUID.

🧾 Invoices & Payments

• list-invoices / get-invoice: Fetch invoices and draft details. list-invoices supports period_start_after/period_start_before (same caveat as subscriptions — no native created-date filter exists). Unlike accounts/subscriptions, Billforward doesn't embed invoice metadata in the base payload — get-invoice always fetches it from the dedicated metadata sub-resource; list-invoices fetches it per-invoice only when includeMetadata=true is passed (adds one extra API call per invoice, so keep limit small).

• list-payments / get-payment / list-receipts: Fetch payments, a single payment by ID (including the offline payment justification text in its description field), and receipts. created_after/created_before are supported on the list tools but Billforward has no native date filter on these endpoints, so matches are filtered client-side after fetching sorted by created.

💳 Pricing & Catalog

• list-products: List the main product lines.

• list-product-rate-plans: List specific rate plans (the entities that accounts subscribe to).

🛡 Security

Enable Read-Only Mode by ensuring the environment variable BILLFORWARD_READ_ONLY=true is set (it is true by default for safety). If the LLM attempts to use tools like create-account or update-subscription while Read-Only is active, the operation will be blocked, and the LLM will receive a descriptive error instructing it to inform you that modifications are disabled.

🧪 Development

Build

pnpm run build

Test

pnpm test

Includes a special protocol.test.ts to ensure no third-party package ever leaks logs to the MCP stream again.