QuickBooks Online MCP Server

A Model Context Protocol server for QuickBooks Online, built on Cloudflare Workers with OAuth 2.0 authentication.

Provides 55 tools for managing QuickBooks entities (customers, invoices, bills, vendors, etc.) via any MCP-compatible client.

Architecture

• Cloudflare Workers runtime with Durable Objects for MCP state
• Hono for HTTP routing and OAuth proxy
• McpAgent (from agents package) for MCP transport (SSE + Streamable HTTP)
• Pure fetch() calls to the QuickBooks REST API — no Node.js SDKs required

api/
├── index.ts              # Hono app: OAuth discovery, /register, /authorize, /token, MCP routes
├── QuickBooksMCP.ts      # McpAgent Durable Object with all tools
├── QuickBooksService.ts  # Fetch-based QB API client (generic CRUD + query builder)
└── lib/
    └── qb-auth.ts        # OAuth middleware and token exchange helpers

Getting Your Intuit Developer Credentials

The Intuit Developer sandbox is completely free — no QuickBooks subscription needed for testing.

Step 1: Create a Free Developer Account

1. Go to developer.intuit.com and sign up (no credit card required)
2. Once registered, Intuit automatically creates a sandbox company with sample data

Step 2: Create an App

1. After logging in, go to My Hub > App Dashboard
2. Click Create an app
3. Select QuickBooks Online and Payments
4. Name it anything (e.g. "QBO MCP Server")
5. Select the com.intuit.quickbooks.accounting scope
6. Click Create app

Step 3: Get Your Client ID and Client Secret

1. Inside your app, click Keys & OAuth in the left nav
2. Make sure you're on the Development tab (not Production)
3. Click Show credentials
4. Copy your Client ID and Client Secret

Step 4: Add the Redirect URI

Still in Keys & OAuth:

1. Scroll to Redirect URIs
2. Click Add URI
3. Add the redirect URI for your MCP client (see table below)
4. Save

MCP Client	Redirect URI
LibreChat (Docker or local)	http://localhost:3080/api/mcp/quickbooks/oauth/callback
MCP Inspector	Use the callback URL shown in the Inspector UI

Setup

1. Install dependencies

npm install

2. Configure secrets

Copy the template and fill in your credentials from the steps above:

cp .dev.vars.template .dev.vars

QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_REALM_ID=your_company_id        # Optional if passed via header
QUICKBOOKS_ENVIRONMENT=sandbox              # 'sandbox' or 'production'

3. Start the server

npx wrangler dev

The server starts at http://localhost:3000.

4. Verify

# Health check
curl http://localhost:3000/

# OAuth discovery
curl http://localhost:3000/.well-known/oauth-authorization-server

MCP Client Configuration

LibreChat

Add to your librechat.yaml:

mcpServers:
  quickbooks:
    type: "streamable-http"
    url: "http://host.docker.internal:3000/mcp"  # Use localhost:3000 if not using Docker
    requiresOAuth: true
    headers:
      X-QB-Realm-Id: "{{QB_REALM_ID}}"
      X-QB-Environment: "{{QB_ENVIRONMENT}}"
    customUserVars:
      QB_REALM_ID:
        title: "QuickBooks Realm ID"
        description: "Your QuickBooks Company ID (found in Intuit Developer Portal under Sandbox settings)"
      QB_ENVIRONMENT:
        title: "QuickBooks Environment"
        description: "Enter 'sandbox' or 'production' (defaults to sandbox)"

You must also add the server's address to mcpSettings.allowedDomains — LibreChat requires this for any local/non-public MCP server URL:

mcpSettings:
  allowedDomains:
    - "http://localhost:3000"

When LibreChat starts, it will:

1. Detect the server needs OAuth and prompt you to authorize
2. Redirect you to Intuit's OAuth page
3. After authorizing, ask you for the Realm ID and Environment via the customUserVar prompts
4. Connect and expose all QuickBooks tools

Other MCP Clients

Connect to /mcp (Streamable HTTP) or /sse (SSE) with:

• Authorization: Bearer {access_token} header (required)
• X-QB-Realm-Id: {company_id} header (required if not set in env)
• X-QB-Environment: sandbox|production header (optional, defaults to sandbox)
• X-QB-Refresh-Token: {refresh_token} header (optional, enables auto-refresh on 401)

Finding Your Realm ID

The Realm ID is the QuickBooks Company ID of the company you want to access. This is not the same as your App ID or the developer account Company ID.

Common confusion: The Intuit Developer Portal shows multiple IDs. Your app has a UUID App ID (e.g. 5ff5fa24-...) and the app overview page shows a Company ID for your developer workspace. Neither of these is the Realm ID. The Realm ID is the Company ID of the sandbox or production company with actual accounting data.

For sandbox:

1. Go to developer.intuit.com → your app → Sandbox tab
2. Under your sandbox company, the Company ID is the Realm ID (a numeric string like 9341456502676660)

For production:

1. Keyboard shortcut (while logged into QBO): Ctrl+Alt+? (Windows) or Control+Option+? (Mac) — shows Company ID on screen
2. Settings page: Gear icon → Subscriptions and billing → Company ID is at the top
3. OAuth callback: Intuit includes realmId as a query parameter in the redirect URL

Available Tools (55)

Full CRUD + search on all 11 QuickBooks entity types:

Entity	Create	Read/Get	Update	Delete	Search
Customer	create_customer	get_customer	update_customer	delete_customer	search_customers
Invoice	create_invoice	read_invoice	update_invoice	delete_invoice	search_invoices
Account	create_account	get_account	update_account	delete_account	search_accounts
Item	create_item	read_item	update_item	delete_item	search_items
Estimate	create_estimate	get_estimate	update_estimate	delete_estimate	search_estimates
Bill	create_bill	get_bill	update_bill	delete_bill	search_bills
Vendor	create_vendor	get_vendor	update_vendor	delete_vendor	search_vendors
Employee	create_employee	get_employee	update_employee	delete_employee	search_employees
Journal Entry	create_journal_entry	get_journal_entry	update_journal_entry	delete_journal_entry	search_journal_entries
Bill Payment	create_bill_payment	get_bill_payment	update_bill_payment	delete_bill_payment	search_bill_payments
Purchase	create_purchase	get_purchase	update_purchase	delete_purchase	search_purchases

Note: Delete on Customer, Vendor, Employee, Account, and Item performs a deactivation (Active: false) since QuickBooks doesn't support hard deletion on these entities. Delete on Invoice performs a void. Delete on Bill, Estimate, Journal Entry, Bill Payment, and Purchase performs a hard delete.

Tool Schemas

All create tools have typed Zod schemas matching the QuickBooks API spec — required fields are enforced, optional fields are documented with descriptions. This gives LLMs clear guidance on what to send. For example, create_bill requires VendorRef and Line items with proper AccountBasedExpenseLineDetail or ItemBasedExpenseLineDetail nesting.

All update tools auto-fetch the current entity to get SyncToken and required fields, so callers only need to provide the Id and the fields they want to change.

All delete tools only need the entity id — SyncToken is fetched automatically.

Search Tools

All search tools accept structured criteria with operators:

{
  "criteria": [
    { "field": "DisplayName", "value": "Acme", "operator": "LIKE" },
    { "field": "Balance", "value": 0, "operator": ">" }
  ],
  "limit": 10,
  "asc": "DisplayName"
}

Supported operators: =, <, >, <=, >=, LIKE, IN

Deployment

Deploy to Cloudflare Workers:

# Set your Cloudflare account ID (find it in the Cloudflare dashboard)
export CLOUDFLARE_ACCOUNT_ID=your_account_id

# Login to Cloudflare
npx wrangler login

# Set secrets (each prompts for the value)
npx wrangler secret put QUICKBOOKS_CLIENT_ID
npx wrangler secret put QUICKBOOKS_CLIENT_SECRET
npx wrangler secret put QUICKBOOKS_REALM_ID        # Optional if passed via header
npx wrangler secret put QUICKBOOKS_ENVIRONMENT      # 'sandbox' or 'production'

# Deploy
npx wrangler deploy

The deploy outputs your worker URL (e.g. https://quickbooks-online-mcp-server.<subdomain>.workers.dev). Update your MCP client config to point to this URL.

Sandbox vs Production

	Sandbox	Production
API Base URL	sandbox-quickbooks.api.intuit.com	quickbooks.api.intuit.com
Data	Sample data from Intuit	Real company data
Cost	Free (developer account only)	Requires QBO subscription (Simple Start+)
App Review	Not required	Required by Intuit
OAuth Keys	Development keys from dev portal	Production keys (after app approval)

Sandbox is the default. Set QUICKBOOKS_ENVIRONMENT=production or pass X-QB-Environment: production header to use production.

License

MIT