mcp-quickbooks 0.1.0

QuickBooks Online MCP server for invoices, customers, and payments. OAuth 2.1 + PKCE, stdio/HTTP.

QuickBooks Online MCP Server

QuickBooks Online MCP server for Claude Desktop and any MCP client, written in Python on the official MCP SDK (FastMCP). It exposes 18 tools over invoices, customers, and payments (create, read, update, delete, list, search) plus read-only company and receivables resources, behind a real OAuth 2.1 authorization-code + PKCE flow with automatic token refresh, client-side rate limiting that honors QuickBooks throttles, and structured errors that tell an agent what to do next. It runs over stdio and Streamable HTTP.

Related: HubSpot CRM MCP Server · MCP Audit Gateway · What production MCP actually requires

Architecture

flowchart LR
    Agent["MCP client<br/>(Claude Desktop / HTTP)"]
    subgraph Server["mcp-quickbooks (FastMCP)"]
        Tools["18 tools<br/>invoices · customers · payments"]
        Resources["resources<br/>company · receivables · customers"]
        Client["QBOClient<br/>retry · backoff · error mapping"]
        RL["RateLimiter<br/>per-second + per-minute buckets"]
        Auth["AuthManager<br/>OAuth 2.1 + PKCE · token refresh"]
        Store[("token store<br/>.qbo_tokens.json")]
    end
    QBO["Intuit QuickBooks Online API<br/>/v3/company/{realmId}"]

    Agent <-->|stdio / streamable-http| Tools
    Agent <-->|resources/read| Resources
    Tools --> Client
    Resources --> Client
    Client --> RL
    Client --> Auth
    Auth <--> Store
    Auth <-->|token + refresh| QBO
    Client -->|REST + query| QBO

The server holds no state and stores no customer data: it is a stateless proxy over the QuickBooks REST API. Tokens live in a local file you control; the client deploys with its own Intuit credentials.

Tools

Every tool returns a structured { "ok": true, ... } result, or { "ok": false, "error": {...} } with a suggestion. Each one carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and a declared output schema.

• create_customer: Create a customer. The display name must be unique; QuickBooks rejects duplicates with error 6240.
• get_customer: Read one customer by Id, including balance, contact details, and the current SyncToken.
• update_customer: Sparse update of an existing customer. Needs the Id and a fresh SyncToken.
• delete_customer: Deactivate a customer (QuickBooks has no hard delete for customers), preserving history.
• list_customers: List customers, most recently updated first, with caller-driven pagination.
• search_customers: Find customers by display-name prefix, exact email, or active flag.
• create_invoice: Create an invoice for an existing customer with one or more line items.
• get_invoice: Read one invoice by Id, including lines, totals, balance, and the current SyncToken.
• update_invoice: Replace an invoice. Lines are replaced wholesale, so send every line it should end with.
• delete_invoice: Delete an invoice permanently. Needs the Id and a fresh SyncToken.
• list_invoices: List invoices, most recent transaction date first, with caller-driven pagination.
• search_invoices: Find invoices by customer Id, transaction-date range, or document number.
• create_payment: Record a payment received, optionally applied against a specific invoice.
• get_payment: Read one payment by Id, including linked transactions and the current SyncToken.
• update_payment: Replace a payment. Dropping the invoice link reopens that invoice's balance.
• delete_payment: Delete a payment permanently. Any invoice it settled goes back to unpaid.
• list_payments: List payments, most recent transaction date first, with caller-driven pagination.
• search_payments: Find payments by customer Id or transaction-date range.

Resources

Read-only JSON:

• qbo://company: company profile and legal address
• qbo://summary/receivables: open/overdue invoice counts and outstanding balance
• qbo://summary/customers: active customers ranked by outstanding balance

Least-privilege scopes

The default scope is com.intuit.quickbooks.accounting only. Add com.intuit.quickbooks.payment (via QBO_SCOPES) solely if you connect payment processing. The scope string is validated at startup against the known Intuit scope set, so a typo fails fast rather than silently under-authorizing. Identity scopes (openid, profile, email) are never requested unless you opt in.

Rate limiting and retries

A dual token-bucket limiter caps outbound traffic under both the QuickBooks per-second and per-minute ceilings (configurable via QBO_REQUESTS_PER_SECOND / QBO_REQUESTS_PER_MINUTE). On 429 the client honors the Retry-After header; on 429/5xx without one it uses exponential backoff with jitter, up to QBO_MAX_RETRIES. A single 401 triggers a token refresh and one transparent retry.

Quickstart

uv venv --python 3.12 .venv
uv pip install -e ".[dev]"

cp .env.example .env       # fill in QBO_CLIENT_ID / QBO_CLIENT_SECRET
mcp-quickbooks auth        # opens Intuit, captures the redirect, stores tokens
mcp-quickbooks status      # verify the token refreshes

mcp-quickbooks stdio       # run over stdio (Claude Desktop)
mcp-quickbooks http --port 8000   # run over Streamable HTTP

Credentials are read lazily. The server starts, answers initialize, and serves tools/list with no QBO_* variables set at all; a tool call without credentials returns a structured 401 telling the caller what to configure. That keeps registry introspection and container smoke tests working without secrets.

Claude Desktop

{
  "mcpServers": {
    "quickbooks": {
      "command": "mcp-quickbooks",
      "args": ["stdio"],
      "env": { "QBO_ENVIRONMENT": "sandbox" }
    }
  }
}

Docker

docker build -t mcp-quickbooks .
docker run --rm -i --env-file .env mcp-quickbooks

Running against a real Intuit sandbox

1. Create an app at the Intuit Developer portal and open its Keys & OAuth section. Copy the Development client id and secret.
2. Add a redirect URI that matches QBO_REDIRECT_URI in your .env (default http://localhost:8765/callback).
3. Create a sandbox company from the developer dashboard; its company id is your QBO_REALM_ID.
4. Set QBO_ENVIRONMENT=sandbox, fill in QBO_CLIENT_ID / QBO_CLIENT_SECRET, then run mcp-quickbooks auth. The browser flow returns a realmId automatically; it is stored alongside the tokens.
5. mcp-quickbooks status confirms the tokens refresh. You are now driving the live sandbox.

Switch QBO_ENVIRONMENT=production (with production keys and a connected company) to point at real books. Credentials and tokens are yours; nothing is committed: .env and .qbo_tokens.json are gitignored.

Tests

The suite runs fully offline. Every QuickBooks and OAuth call is served by an in-memory fake (tests/fake_qbo.py) seeded from recorded-style fixtures in tests/fixtures/, wired in through an httpx mock transport: no network, no real credentials.

uv run pytest

Registry metadata

server.json describes the server for the MCP registry, and .mcp.json is the client-config snippet directory crawlers look for. Publishing is intentionally left as a manual step. See PUBLISHING.md. Nothing here submits to any registry.

Hire me

I make AI-era and money-critical integrations production-safe: real auth, real rate limits, real error handling, real tests. Available for MCP server builds and API-integration hardening. Portfolio and contact: https://amin-ale.github.io/portfolio-site · [e-mail]

License

MIT: see LICENSE.