{
"markdown": "# QuickBooks Online MCP Server\n\n\n\n[](https://github.com/amin-ale/mcp-quickbooks/actions/workflows/ci.yml)\n[](https://www.python.org/)\n[](./LICENSE)\n\nQuickBooks Online MCP server for Claude Desktop and any MCP client, written in Python on the official\nMCP SDK (FastMCP). It exposes 18 tools over invoices, customers, and payments (create, read, update,\ndelete, list, search) plus read-only company and receivables resources, behind a real OAuth 2.1\nauthorization-code + PKCE flow with automatic token refresh, client-side rate limiting that honors\nQuickBooks throttles, and structured errors that tell an agent what to do next. It runs over stdio and\nStreamable HTTP.\n\nRelated: [HubSpot CRM MCP Server](https://github.com/amin-ale/hubspot-mcp-server) ·\n[MCP Audit Gateway](https://github.com/amin-ale/mcp-audit-gateway) ·\n[What production MCP actually requires](https://amin-ale.github.io/portfolio-site/what-production-mcp-actually-requires.html)\n\n## Architecture\n\n```mermaid\nflowchart LR\n Agent[\"MCP client
(Claude Desktop / HTTP)\"]\n subgraph Server[\"mcp-quickbooks (FastMCP)\"]\n Tools[\"18 tools
invoices · customers · payments\"]\n Resources[\"resources
company · receivables · customers\"]\n Client[\"QBOClient
retry · backoff · error mapping\"]\n RL[\"RateLimiter
per-second + per-minute buckets\"]\n Auth[\"AuthManager
OAuth 2.1 + PKCE · token refresh\"]\n Store[(\"token store
.qbo_tokens.json\")]\n end\n QBO[\"Intuit QuickBooks Online API
/v3/company/{realmId}\"]\n\n Agent <-->|stdio / streamable-http| Tools\n Agent <-->|resources/read| Resources\n Tools --> Client\n Resources --> Client\n Client --> RL\n Client --> Auth\n Auth <--> Store\n Auth <-->|token + refresh| QBO\n Client -->|REST + query| QBO\n```\n\nThe 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.\n\n## Tools\n\nEvery 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.\n\n- `create_customer`: Create a customer. The display name must be unique; QuickBooks rejects duplicates with error 6240.\n- `get_customer`: Read one customer by Id, including balance, contact details, and the current SyncToken.\n- `update_customer`: Sparse update of an existing customer. Needs the Id and a fresh SyncToken.\n- `delete_customer`: Deactivate a customer (QuickBooks has no hard delete for customers), preserving history.\n- `list_customers`: List customers, most recently updated first, with caller-driven pagination.\n- `search_customers`: Find customers by display-name prefix, exact email, or active flag.\n- `create_invoice`: Create an invoice for an existing customer with one or more line items.\n- `get_invoice`: Read one invoice by Id, including lines, totals, balance, and the current SyncToken.\n- `update_invoice`: Replace an invoice. Lines are replaced wholesale, so send every line it should end with.\n- `delete_invoice`: Delete an invoice permanently. Needs the Id and a fresh SyncToken.\n- `list_invoices`: List invoices, most recent transaction date first, with caller-driven pagination.\n- `search_invoices`: Find invoices by customer Id, transaction-date range, or document number.\n- `create_payment`: Record a payment received, optionally applied against a specific invoice.\n- `get_payment`: Read one payment by Id, including linked transactions and the current SyncToken.\n- `update_payment`: Replace a payment. Dropping the invoice link reopens that invoice's balance.\n- `delete_payment`: Delete a payment permanently. Any invoice it settled goes back to unpaid.\n- `list_payments`: List payments, most recent transaction date first, with caller-driven pagination.\n- `search_payments`: Find payments by customer Id or transaction-date range.\n\n## Resources\n\nRead-only JSON:\n\n- `qbo://company`: company profile and legal address\n- `qbo://summary/receivables`: open/overdue invoice counts and outstanding balance\n- `qbo://summary/customers`: active customers ranked by outstanding balance\n\n## Least-privilege scopes\n\nThe 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.\n\n## Rate limiting and retries\n\nA 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.\n\n## Quickstart\n\n```bash\nuv venv --python 3.12 .venv\nuv pip install -e \".[dev]\"\n\ncp .env.example .env # fill in QBO_CLIENT_ID / QBO_CLIENT_SECRET\nmcp-quickbooks auth # opens Intuit, captures the redirect, stores tokens\nmcp-quickbooks status # verify the token refreshes\n\nmcp-quickbooks stdio # run over stdio (Claude Desktop)\nmcp-quickbooks http --port 8000 # run over Streamable HTTP\n```\n\nCredentials 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.\n\n### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"quickbooks\": {\n \"command\": \"mcp-quickbooks\",\n \"args\": [\"stdio\"],\n \"env\": { \"QBO_ENVIRONMENT\": \"sandbox\" }\n }\n }\n}\n```\n\n### Docker\n\n```bash\ndocker build -t mcp-quickbooks .\ndocker run --rm -i --env-file .env mcp-quickbooks\n```\n\n## Running against a real Intuit sandbox\n\n1. 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.\n2. Add a redirect URI that matches `QBO_REDIRECT_URI` in your `.env` (default `http://localhost:8765/callback`).\n3. Create a **sandbox company** from the developer dashboard; its company id is your `QBO_REALM_ID`.\n4. 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.\n5. `mcp-quickbooks status` confirms the tokens refresh. You are now driving the live sandbox.\n\nSwitch `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.\n\n## Tests\n\nThe 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.\n\n```bash\nuv run pytest\n```\n\n## Registry metadata\n\n`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.\n\n## Hire me\n\nI 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\n\n## License\n\nMIT: see [LICENSE](./LICENSE).\n",
"bytes": 8243,
"sha": "1c1ba3ce4aa79e1c57d0da1f878b26b1bf390c7f7f499226be6a50fcf163125d",
"repo_slug": "amin-ale/mcp-quickbooks",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_amin_ale_mcp_quickbooks_2b98eb1b/readme"
}