QuickBooks Online MCP Server

QuickBooks Online MCP Server

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

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

Architecture

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.

Shortened. The full README is on GitHub.