mcp-quickbooks

# QuickBooks Online MCP Server

<!-- mcp-name: io.github.amin-ale/mcp-quickbooks -->

[![CI](https://github.com/amin-ale/mcp-quickbooks/actions/workflows/ci.yml/badge.svg)](https://github.com/amin-ale/mcp-quickbooks/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)

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](https://github.com/amin-ale/hubspot-mcp-server) ·
[MCP Audit Gateway](https://github.com/amin-ale/mcp-audit-gateway) ·
[What production MCP actually requires](https://amin-ale.github.io/portfolio-site/what-production-mcp-actually-requires.html)

## Architecture

```mermaid
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

```bash
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

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

### Docker

```bash
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](https://developer.intuit.com/) 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.

```bash
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 · amin.ale.business@gmail.com

## License

MIT: see [LICENSE](./LICENSE).