QuickBooks Online MCP Server

An MCP server for the QuickBooks Online Accounting API (v3). It lets an AI agent read one QuickBooks company's customers, vendors, items, accounts, invoices, estimates, payments, bills, purchases, journal entries, time activities, attachments and financial reports and, on explicit request, create, update and void records, email invoices and upload attachments.

• Transport: MCP Streamable HTTP at POST /mcp, health probe at GET /health

• Stateless and multi-tenant: the OAuth access token and company (realm) id arrive on every request as HTTP headers and are never stored; every tool is listed from the first tools/list

• Python 3.12, uv, FastMCP, httpx

• License: Apache-2.0, Copyright 2026 MSPbots.ai

Authentication headers

Where to get them: the access token and realm id come from the OAuth 2.0 authorization of a QuickBooks Online app (Intuit developer portal) with the com.intuit.quickbooks.accounting scope. The realm id is returned with the authorization callback. Access tokens expire after about an hour; the caller (for example a gateway) refreshes them and sends the current one. This server never refreshes or stores tokens.

How they are sent to QuickBooks: the token as Authorization: Bearer <token> to https://quickbooks.api.intuit.com/v3/company/<realm>/... (or the sandbox host), with minorversion=75 on every call. Values that look like unresolved templates (${...}) are treated as missing.

A request to /mcp without the required headers gets HTTP 401 naming them; a non-numeric realm id or an unknown environment gets HTTP 400.

Related MCP server: QuickBooks Online MCP Server

Tools

All 138 tools return a JSON string. Names follow qbo_<records>_<action>.

Generic actions, per area:

List and search results look like {items, count, startPosition, maxResults, has_more, next_startPosition}.

Special tools:

Errors come back as a JSON envelope instead of an exception:

{"error": {"code": "invalid_argument", "message": "QuickBooks rejected customer: Stale Object Error: You and another user were working on this at the same time. (code 5010)", "retryable": false}}

code is one of not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error. A Fault returned with HTTP 200 is also reported as an error. Reads (including queries) are retried with backoff on 429, 5xx and network errors; writes only on 429.

Run locally

uv sync
uv run python -m qbo_mcp          # listens on 0.0.0.0:8080

or with Docker:

docker build --platform linux/amd64 -t qbo-mcp:dev .
docker run --rm -p 8080:8080 qbo-mcp:dev

Configuration (environment variables, all optional): MCP_HTTP_HOST (default 0.0.0.0), MCP_HTTP_PORT (default 8080), LOG_LEVEL (default INFO). Credentials are never read from the environment.

Testing example

# list tools
curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Qbo-Access-Token: <access-token>" \
  -H "X-Qbo-Realm-Id: 9130350000000001" \
  -H "X-Qbo-Environment: sandbox" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# unpaid invoices
curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Qbo-Access-Token: <access-token>" \
  -H "X-Qbo-Realm-Id: 9130350000000001" \
  -H "X-Qbo-Environment: sandbox" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"qbo_invoices_list","arguments":{"status":"Unpaid"}}}'

Unit tests (no network access needed):

uv run pytest

Delivery notes

• Same tool contract. All 138 tool names and their required parameters are unchanged from the older version, and the same three X-Qbo-* headers are used.

• All tools always listed. qbo_navigate remains for compatibility and only describes an area's tools.

• Query escaping. Search terms are escaped the way the QuickBooks query language expects (backslash before ' and \); the older version doubled quotes, which QuickBooks does not treat as an escape.

• Updates. Updates are always sparse and need the current SyncToken (from _get); an update with no changed fields is rejected before calling QuickBooks.

• Not included. The older version's interactive invoice card (an MCP Apps ui:// resource) is not part of this server; invoice tools return plain JSON.

• Tokens. The server does not refresh OAuth tokens; send a current access token on every request.

License

Apache License 2.0 - see LICENSE and NOTICE.