mcp-quickbooks

A production-shaped Model Context Protocol server for QuickBooks Online, built on the official Python MCP SDK (FastMCP). It gives an LLM agent typed, least-privilege tools to create, read, update, delete, list, and search invoices, customers, and payments, plus read-only resources for company and receivables summaries — behind a real OAuth 2.1 authorization-code + PKCE flow with automatic token refresh, client-side rate limiting that honors QuickBooks throttles, and structured, actionable error responses. It runs over both stdio and Streamable HTTP.

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.

Capabilities

Tools (each returns a structured { "ok": true, ... } result, or { "ok": false, "error": {...} } with a suggestion):

Entity	create	read	update	delete	list	search
Customer	create_customer	get_customer	update_customer	delete_customer*	list_customers	search_customers
Invoice	create_invoice	get_invoice	update_invoice	delete_invoice	list_invoices	search_invoices
Payment	create_payment	get_payment	update_payment	delete_payment	list_payments	search_payments

* QuickBooks Online has no hard delete for customers, so delete_customer deactivates (Active = false) and says so in its tool description — history is preserved.

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

Claude Desktop

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

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 (MCP registry schema) and smithery.yaml (Smithery) describe the server for discovery. 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 · amin.ale.business@gmail.com

License

MIT — see LICENSE.