A
licenseA
qualityA
maintenanceEnables AI assistants to manage BuchhaltungsButler bookkeeping through all 48 API endpoints, with safety-categorized tools for read, write, and destructive operations.
46
20 npm
9
MIT
billforward-mcp
by GregoriSoria
The Billforward MCP server integrates Billforward's billing and subscription management API with LLMs, enabling read and write operations across accounts, subscriptions, invoices, payments, and product catalogs.
Search & Insights
search– Unified search across accounts, subscriptions, and invoices by email, ID, or keywordget-customer-summary– 360-degree customer dashboard combining account details, subscriptions, credit balances, and recent invoicesget-metadata-schema– Discover custom metadata fields in use across accounts, subscriptions, and invoices
Guidance & Auth
help– Overview of available tools and usage patternsget-me– Validate API credentials and view authenticated user/org info
Account Management
List, get by ID or email, create, and update customer accounts; list profiles; supports filtering by metadata and date range
Subscription Management
List, get details, create, and cancel subscriptions, with billing period date filters
Invoices & Payments
List and retrieve invoices (with line items, taxes, payment status), payments, and receipts; supports date-based filtering
Catalog & Pricing
List products and rate plans; get full rate plan details including pricing components and tiers
Security & Configuration
Configurable read-only mode (
BILLFORWARD_READ_ONLY) blocks mutation operations and returns instructional errors for LLMsConfigurable via environment variables: API tokens (sandbox/production), custom API URLs, result limits, and request timeouts
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@billforward-mcp get customer summary for john@example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Billforward MCP Server
This MCP server connects LLMs to Billforward through a small always-on tool surface: lookup resolves prefixed IDs and free-text search, while search-tools, describe-tool, and call-api discover and execute operations from an in-package API catalog—covering the full API without registering hundreds of per-endpoint tools.
flowchart LR
Model --> AlwaysOn
AlwaysOn --> Lookup
AlwaysOn --> ToolSearch
AlwaysOn --> Help
ToolSearch -->|"matches"| Catalog
Catalog --> Describe
Describe --> Call
Lookup -->|"PREFIX-id"| GetById
Lookup -->|"email/texto"| SearchV3Configuration
Primary config: BILLFORWARD_ENVIRONMENTS — a JSON object of named environments (lowercase slugs you choose). Each entry needs token and type (sandbox or production); readonly defaults to true (only JSON false enables writes). Optional baseUrl overrides the default for that type.
BILLFORWARD_ENVIRONMENTS='{"dev":{"token":"your_dev_token","type":"sandbox","readonly":true},"staging":{"token":"your_staging_token","type":"sandbox","readonly":true},"prod":{"token":"your_production_token","type":"production","readonly":true}}'With one environment configured, tools select it automatically. With two or more, pass the exact name via each tool's environment parameter.
Create a local .env from the template and keep every environment read-only until writes are explicitly needed:
cp .env.example .envBILLFORWARD_ENVIRONMENTS='{"dev":{"token":"your_dev_token","type":"sandbox","readonly":true},"staging":{"token":"your_staging_token","type":"sandbox","readonly":true},"prod":{"token":"your_production_token","type":"production","readonly":true}}'
BILLFORWARD_TIMEOUT=15000MCP client setup
.mcp.json (loads .env from workspace root):
{
"mcpServers": {
"billforward": {
"command": "bash",
"args": ["-lc", "set -a; source .env; set +a; exec npx -y billforward-mcp"]
}
}
}VS Code / Cursor (.vscode/mcp.json):
{
"servers": {
"billforward": {
"type": "stdio",
"command": "npx",
"args": ["-y", "billforward-mcp"],
"envFile": "${workspaceFolder}/.env"
}
}
}Inline env (when the client does not load env files):
{
"mcpServers": {
"billforward": {
"command": "npx",
"args": ["-y", "billforward-mcp"],
"env": {
"BILLFORWARD_ENVIRONMENTS": "{\"dev\":{\"token\":\"your_dev_token\",\"type\":\"sandbox\",\"readonly\":true},\"staging\":{\"token\":\"your_staging_token\",\"type\":\"sandbox\",\"readonly\":true},\"prod\":{\"token\":\"your_production_token\",\"type\":\"production\",\"readonly\":true}}"
}
}
}
}Related MCP server: blesta-mcp
How to Get Your API Token
Log in to your Billforward environment.
Go to Setup > Personal > API Keys.
Create a token and copy it.
Available Tools
Discovery (always on)
Tool | Purpose |
| Prefixed ID ( |
| Keyword search over the API catalog → operation names |
| Full schema for one catalog entry (method, path, params) |
| Execute a catalog entry by name (writes need a write-enabled environment) |
| Developer guide and configured environment summary |
| Validate credentials via |
Typical flow: lookup for IDs and text search → search-tools → describe-tool → call-api for lists and writes.
Convenience
Tool | Purpose |
| Paginated account search with metadata filters |
| Account-scoped subscriptions and invoices |
| 360° view: profile, subscriptions, recent invoices, dunning |
| Custom metadata keys in use across accounts, subscriptions, invoices |
Upgrading to 2.0
Version 2.0 replaces per-endpoint tools with discovery-first tools. Ops are unchanged (npx billforward-mcp + env tokens).
Old tool | Replacement |
|
|
|
|
|
|
dedicated |
|
Full changelog: CHANGELOG.md on GitHub
Security
Named environments default to read-only (readonly: true). Only set "readonly": false for environments that should allow writes.
When read-only is active, write catalog entries (create-account, update-subscription, etc.) are blocked with a descriptive error.
Development
pnpm run build
pnpm testAvailable Tools
23 toolscancel-subscriptionA
Cancel an active subscription. By default, cancels at the end of the current billing period.
Inputs: subscriptionId (required), cancellationAction.
create-accountB
Create a new account in Billforward. This is the first step for new customers.
Inputs: profile (required).
create-subscriptionB
Create a new subscription for an account to a specific product rate plan.
Inputs: accountId (required), productRatePlanId (required), name, state.
get-accountA
Get detailed information about a specific account by ID. Contains billing contact info and linked metadata.
Inputs: accountId (required).
get-account-by-emailA
Find an account specifically by their email address. This is the fastest way to find a customer if you have their email.
Inputs: email (required).
get-customer-summaryA
Provides a 360-degree view of a customer. Combines account details, active subscriptions, credit balances, and recent invoice history into one compact dashboard. Use this for quick context before troubleshooting or churn analysis.
Inputs: query (required).
get-invoiceA
Get full details for a specific invoice. Includes line items, taxes, and payment status.
Inputs: invoiceId (required).
get-meA
Validate API credentials and get information about the authenticated user/organization.
Inputs: no named parameters.
get-metadata-schemaA
Analyzes recently used metadata keys across Accounts and Subscriptions to provide a 'cheat sheet' of available custom fields (e.g., salesforce_account_id, duns). Use this to discover how to filter using the 'metadata' parameter.
Inputs: no named parameters.
get-paymentA
Get full details for a specific payment by ID. Includes the offline payment justification (the 'description' field) when the payment was recorded manually rather than through a gateway.
Inputs: paymentId (required).
get-rate-planA
Get detailed information about a specific product rate plan by ID or Data Name. This will return the full structure including pricing components and pricing tiers, essential for understanding how the plan is billed.
Inputs: ratePlanIdOrName (required).
get-subscriptionA
Get detailed state for a specific subscription by its unique ID. Includes current period start/end and pricing component states.
Inputs: subscriptionId (required).
helpA
Get concise developer guidance on available Billforward MCP tools and entities. Use this if you are unsure which tool to use.
Inputs: no named parameters.
list-accountsB
List merchant accounts with support for pagination, sorting, and metadata filtering. Available fields include id, crmID, userID, created, updated, and an embedded profile (email, names, address). Use metadata filtering via 'meta.key=value'.
Inputs: limit, offset, orderBy, metadata, +3 more.
list-invoicesA
List all invoices with pagination and sorting. Invoices represent a request for payment for a period of service. Note: Billforward has no native filter on invoice creation date — period_start_after/period_start_before filter by the invoice's billing period start instead.
Inputs: limit, offset, orderBy, orderDirection, +2 more.
list-paymentsA
List payments across all accounts with pagination and sorting. Payments are records of money received into the system. Note: Billforward has no native created-date filter on this endpoint — when created_after/created_before are set, results are fetched sorted by created (regardless of orderBy) and filtered client-side.
Inputs: limit, offset, orderBy, created_after, +2 more.
list-product-rate-plansC
List all product rate plans. Rate plans define the pricing and logic for a product subscription.
Inputs: limit, offset, orderBy, orderDirection.
list-productsB
List all products in the catalog. Products are the highest level of the billing hierarchy.
Inputs: limit, offset, orderBy, orderDirection.
list-profilesB
List all account profiles. Profiles contain contact details like firstName, lastName, email, and address fields.
Inputs: limit, offset.
list-receiptsA
List receipts across all accounts. Receipts usually map 1-to-1 with successful payments and provide audit data. Note: Billforward has no native created-date filter on this endpoint — when created_after/created_before are set, results are fetched sorted by created (regardless of orderBy) and filtered client-side.
Inputs: limit, offset, orderBy, created_after, +2 more.
list-subscriptionsA
List all subscriptions with pagination and sorting. Use this to monitor customer subscription states (Active/Cancelled) and upcoming renewals. Note: Billforward has no native filter on subscription creation date — period_start_after/period_start_before filter by the current billing period start instead.
Inputs: limit, offset, orderBy, orderDirection, +2 more.
searchA
Perform a lightweight unified search across Accounts, Subscriptions, and Invoices. Automatically detects emails, IDs, or falls back to metadata/name filtering.
Inputs: query (required), limit.
update-accountA
Update an existing account profile. Billforward uses PUT for updates, so pass all relevant profile fields.
Inputs: profile (required), accountId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A3.6/5.0
Scored across 23 tools
Disambiguation4/5
Tools are generally distinct, with some overlap between list-accounts and list-profiles, and between get-account, get-account-by-email, and get-customer-summary. However, descriptions clarify their specific use cases, so ambiguity is low.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create-account, list-invoices), making the tool surface predictable and easy to navigate.
Tool Count4/5
23 tools is slightly above the typical range but still appropriate for a comprehensive billing and subscription management system. Each tool covers a distinct operation, though some consolidation could be possible.
Completeness3/5
The set covers core CRUD for accounts and subscriptions, but lacks update for subscriptions and missing operations for invoices and payments (only retrieve and list). Products and rate plans are only listable, and there is no creation or deletion for many entities.
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues
Related MCP Connectors
Every Canopy public API operation as a tool, run as you after a browser sign-in or on an API key.
Query and manage Amberflo metering & billing: customers, meters, usage, plans, invoices, prepaid.
Manage Apollo invoices and customers with entity-scoped OAuth and optional read/write access.
Read and write Sage Intacct from Claude or ChatGPT. Write tools are flagged for approval.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables LLM agents and MCP clients to interact with the Blesta billing API. It provides read-only tools for searching clients, invoices, services, transactions, and payment accounts, plus optional write tools for creating invoices, managing services, recording payments, and generating customer-facing payment links.33GPL 3.0
- AlicenseAqualityBmaintenanceEnables natural-language access to the Buildium property-management API, exposing all 462 operations through 19 tools. Sandbox is the default, with production read-only modes enforced at the transport layer for safe writes.20MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to safely inspect Stripe billing data such as subscriptions, invoices, failed payments, and churn, with read-only access, per-tool permissions, and a tamper-evident audit log.5 npmMIT