QuickBooks Online MCP Server

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

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

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.

Every tool returns a structured{ "ok": true, ... }result, or{ "ok": false, "error": {...} }with asuggestion. 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.

- 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

The default scope iscom.intuit.quickbooks.accountingonly. Addcom.intuit.quickbooks.payment(viaQBO_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.

A dual token-bucket limiter caps outbound traffic under both the QuickBooks per-second and per-minute ceilings (configurable viaQBO_REQUESTS_PER_SECOND/QBO_REQUESTS_PER_MINUTE). On429the client honors theRetry-Afterheader; on429/5xxwithout one it uses exponential backoff with jitter, up toQBO_MAX_RETRIES. A single401triggers a token refresh and one transparent retry.

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, answersinitialize, and servestools/listwith noQBO_*variables set at all; a tool call without credentials returns a structured401telling the caller what to configure. That keeps registry introspection and container smoke tests working without secrets.

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

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

- Create an app at theIntuit Developer portaland open itsKeys & OAuthsection. Copy theDevelopmentclient id and secret.
- Add a redirect URI that matchesQBO_REDIRECT_URIin your.env(defaulthttp://localhost:8765/callback).
- Create asandbox companyfrom the developer dashboard; its company id is yourQBO_REALM_ID.
- SetQBO_ENVIRONMENT=sandbox, fill inQBO_CLIENT_ID/QBO_CLIENT_SECRET, then runmcp-quickbooks auth. The browser flow returns arealmIdautomatically; it is stored alongside the tokens.
- mcp-quickbooks statusconfirms the tokens refresh. You are now driving the live sandbox.

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

Remote MCP server (streamable HTTP, OAuth 2.1) for AdMake AI. Generate Facebook, Instagram and TikTok ad creatives and UGC-style video ads, research competitor ads from the Meta Ad Library, and publish finished ads to Meta via the Marketing API. Connect at https://admakeai.com/api/mcp