QBO MCP · remote Model Context Protocol server

Your QuickBooks books,
fluent in AI.

A production MCP server that lets Claude, ChatGPT, Cursor or your own agents read, write and analyse QuickBooks Online. 126 tools on one reusable service layer, multi-company OAuth 2.0, encrypted token vault, validated and audited writes. It is running against the QuickBooks sandbox right now.

Run a live tool call
MCP tools
126
Companies connected
0
Calls audited, 24 h
0
Uptime
-
Agent session · hq/mcp
write create_invoice · validated
audit 3 writes logged
oauth token refreshed
TypeScriptofficial MCP SDK
Streamable HTTPstateless /mcp
Intuit OAuth 2.0auto refresh
AES-256-GCMtoken vault
Sandbox + Productionper company
Full source + IPno 3rd-party connectors

Live console

Click a question. Watch the real server answer it.

Each card sends a JSON-RPC tools/call to /mcp with a demo API key that has read-write access to company hq and read-only access to branch. Responses come straight from the QuickBooks sandbox.

pick a card
Choose a question on the left. The answer is computed live from QuickBooks.

      

    

  

  

    
Audit trail
every write, validation and denial, as it happens

    
  1. No activity yet.

  







  

    
Architecture

    
One service layer, not 120 one-off wrappers.

    
Every tool is a small declaration on top of shared layers: authentication, company context, a QuickBooks client with retries and rate limiting, and accounting services. Adding a custom tool is one file.

  

  

    
      Request path through the QBO MCP server
      
        
        
      
      
      
      
      
      AI clientsClaude · ChatGPTCursor · agents
      HTTPS /mcpStreamable HTTPBearer API keysper-key rate limithttp/app.ts
      Tool registry126 tools · Zod schemaspermission checkvalidate_onlyaudit logAI-friendly errorstools/registry.ts
      Company contextselect / switchread · read_writeservices.ts
      Accounting servicesreconciliation · closeforecast · KPIsanalysis/core.ts
      QBO clienttoken refresh450/min · 8 parallelretry · idempotencyqbo/client.ts
      AES-256-GCM vault
      
      QuickBooks

    
    

      
Stateless by design. Each POST builds a fresh MCP server bound to the caller's key, so it scales horizontally behind any load balancer.

      
One QuickBooks client. Queries, CRUD, reports, change data capture, PDFs, e-mail and uploads share retries, throttling and error mapping.

      
Errors an agent can act on. QuickBooks faults become validation, stale_object, rate_limited and similar, each with a hint and the intuit_tid.

    

  







  

    
Tool catalogue

    
126 tools across every area in the brief.

    
Read tools are safe to call freely. Write tools validate first and support validate_only. Delete and void stay hidden until an administrator enables them for a key and company.

  

  

    

    
  

  







  

    
Multi-company

    
Every company in its own lane.

    
Each QuickBooks company connects through its own OAuth consent and keeps its own encrypted tokens. API keys are granted per company, read or read-write, so an agent can see the branch without being able to change it. Cross-company comparison only includes companies the key may read.

    
    
      
  • list_companies and select_company switch the default; any call can pass company.
    • 
      
  • Sandbox and production companies side by side, each with its own Intuit keys.
    • 
      
  • Connection links are single-use, expire, and are bound to an OAuth state.
    • 
    

  

  

    
API keyhqbranch

    
Finance agentread · writeread · write

    
Live demo consoleread · writeread only

    
Board reporting botread onlyread only

    
Controllerwrite + voidno access

    
Write attempts outside a grant are refused and written to the audit log. Try it in the console: "Write to a read-only company".

  







  

    
Security and safety

    
Built for money, not for demos.

  

  

    
Encrypted token vault
Access and refresh tokens are sealed with AES-256-GCM, bound to the company realm, never logged and never sent to the AI.

    
Refresh without races
Tokens refresh five minutes early, one refresh per company even under parallel calls, and the newest refresh token is always kept.

    
Validated writes
Debits equal credits, accounts exist and are active, A/R and A/P lines carry a name, no posting into a closed period. Problems stop the write.

    
Destructive off by default
Delete and void need a global switch, a per-company grant and a confirm field that repeats the record id.

    
Audit log
Every write, dry run and denied attempt is stored with key, company, tool, record and outcome.

    
Rate limits both ways
Per API key for callers, and 450 requests a minute with 8 in flight per company towards QuickBooks, under Intuit's limits.

    
Idempotent retries
Write calls carry an Intuit requestid, so a retried POST after a timeout cannot create a duplicate invoice.

    
Hardened runtime
Non-root, read-only container, secrets from the environment, HSTS, health and readiness probes.

  







  

    
Testing and validation

    
Tested in code, then against the real sandbox.

  

  

    
26 / 26automated tests pass: HTTP, auth, permissions, validation, token refresh, report parsing, analysis

    
-tools exercised live against the QuickBooks sandbox, read and write

    
MCP SDK clientend-to-end through the official MCP client over Streamable HTTP

  

  







  

    
Connect a client

    
Point any MCP client at it.

    
The demo key below has read-write access to the sandbox company hq and read-only access to branch.

  

  

    

      
    

    

  







  

    
Delivery plan

    
Most of the platform already runs. The rest is mapping your spec.

  

  

    
Done now
Core platform
  • Remote /mcp, official SDK, stateless
  • Intuit OAuth, refresh, encrypted vault
  • Multi-company, grants, switching
  • Service layer, registry, audit, health
  • 126 tools across all brief areas

    
Week 1
Your proof of concept
  • Review the existing PoC and keep what works
  • Map the 120-tool specification to the registry
  • Gap list with effort per tool

    
Weeks 2 to 3
Phase 1 sign-off
  • Your auth model and hosting
  • Spec tools completed and named your way
  • Sandbox read and write validation report

    
Weeks 4 to 5
Phase 2 and launch
  • Advanced reconciliation and analysis per spec
  • Production keys, deployment, monitoring
  • Docs, handover, source and IP transfer