QuickBooks Online

A FastMCP server that exposes QuickBooks Online operations (read invoices, look up customers/items, and create invoices) over streamable HTTP with static bearer-token auth.

What's here

• src/qbo_mcp/config.py — typed env-var settings.
• src/qbo_mcp/token_store.py — Upstash Redis REST persistence for the OAuth token bundle.
• src/qbo_mcp/qbo_client.py — async QBO API client (generic transport) with auto-refresh, refresh-token rotation, retry-on-401, rate-limit + Fault handling, and the id/date/escape validators.
• src/qbo_mcp/service.py — QBOService, the business layer that builds validated/escaped queries and invoice payloads on top of the client.
• src/qbo_mcp/server.py — root FastMCP server (bearer auth + /health) that mounts the per-entity tool sub-servers in src/qbo_mcp/tools/.
• scripts/bootstrap_oauth.py — one-time OAuth flow.
• scripts/smoke_test.py — verifies tokens + connectivity.

Tools

Tool	Purpose
search_customers(name)	Find active customers by partial display name → customer_id.
list_items(name?)	List active catalog items (Service/NonInventory/Inventory) → item_id + unit price.
get_invoices(customer_id, status?, from_date?, to_date?)	A customer's invoices (status all/open/paid, optional ISO date range), newest first, with a one-line summary each.
get_invoice(doc_number)	Full detail of one invoice by its human-facing document number, with a deep link.
create_invoice(customer_id, lines[], due_date?, customer_memo?)	Create an invoice; each line's unit_price defaults to the item's catalog price. Confirm details with the user first — this writes to QuickBooks.

Workflow the docstrings teach the LLM: search_customers → list_items → confirm lines with the user → create_invoice.

Prerequisites

• Python 3.12
• uv

1. Create an Intuit developer app

1. Sign in at https://developer.intuit.com and create a new app under "QuickBooks Online and Payments".
2. Enable the com.intuit.quickbooks.accounting scope.
3. Under Keys & OAuth, copy the Client ID and Client Secret (use the Development keys for the sandbox).
4. Add this redirect URI: http://localhost:8000/callback.

2. Create an Upstash Redis database

1. Sign in at https://console.upstash.com and create a Redis database.
2. From the database's REST section, copy the REST URL and REST Token.

3. Configure environment

cp .env.example .env
# Fill in INTUIT_CLIENT_ID, INTUIT_CLIENT_SECRET, UPSTASH_REDIS_REST_URL,
# UPSTASH_REDIS_REST_TOKEN, MCP_BEARER_TOKEN.
# Leave QBO_REALM_ID blank — the bootstrap step prints it.

4. Install dependencies

uv sync

5. Authorize against QBO

uv run python scripts/bootstrap_oauth.py

A browser tab opens for Intuit consent. When it completes, the script prints something like:

realmId=9341454... — set QBO_REALM_ID=9341454... in .env

Paste that value into .env.

6. Smoke test

uv run python scripts/smoke_test.py

Expected output: Company: <your sandbox company name>.

7. Run the MCP server

uv run python -m qbo_mcp.server   # serves on 0.0.0.0:$PORT (default 8080)

• MCP endpoint: http://localhost:8080/mcp (streamable HTTP), authenticated with Authorization: Bearer <MCP_BEARER_TOKEN>.
• Unauthenticated GET /health returns ok (for health checks).

Connect from Claude Code:

claude mcp add --transport http qbo http://localhost:8080/mcp \
  --header "Authorization: Bearer <MCP_BEARER_TOKEN>"

Or inspect it with the MCP Inspector (npx @modelcontextprotocol/inspector) → Transport "Streamable HTTP" → URL http://localhost:8080/mcp → header Authorization: Bearer <MCP_BEARER_TOKEN>.

Docker / Render deployment

The server ships as a container (self-hosted as a Docker image on Render). The image is a multi-stage uv build on python:3.12-slim, runs as a non-root user, and bakes in no config — every secret/setting is supplied at runtime via env vars (the same ones listed in .env.example). It honors $PORT (Render injects it; defaults to 8080) and serves the unauthenticated GET /health route for Render's health probe.

Build the image:

docker build -t quickbooks-online-mcp .

Run locally with Docker Compose, mirroring the Render runtime — config comes from a local env file (never committed):

docker compose up --build                       # bearer mode (reads .env)
ENV_FILE=.env.oauth docker compose up --build   # oauth mode
PORT=9090 docker compose up --build             # custom port, as Render injects $PORT

Then GET /health and the /mcp endpoint are served on $PORT exactly as the uv run path above (e.g. curl localhost:8080/health → ok; connect an MCP client to http://localhost:8080/mcp).

CI builds and publishes the image to GitHub Container Registry at ghcr.io/ashcir/quickbooks-online-mcp (tagged :latest plus a sha-<commit> tag). On Render, deploy from that image and enter the runtime env vars (auth mode + QBO/Upstash credentials) as encrypted dashboard settings — no .env* is part of the image.

Tests

uv run pytest -q

Project layout

src/qbo_mcp/        # config, token_store, qbo_client, service, server
src/qbo_mcp/tools/  # per-entity FastMCP sub-servers mounted by server.py
scripts/            # bootstrap + smoke test
tests/              # pytest suite (mocked httpx)