LibreChat-AI/quickbooks-online-mcp

README

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

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

Step 2: Create an App

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

Step 3: Get Your Client ID and Client Secret

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

Step 4: Add the Redirect URI

Still in Keys & OAuth:

Scroll to Redirect URIs
Click Add URI
Add the redirect URI for your MCP client (see table below)
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:

Detect the server needs OAuth and prompt you to authorize
Redirect you to Intuit's OAuth page
After authorizing, ask you for the Realm ID and Environment via the customUserVar prompts
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:

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

For production:

Keyboard shortcut (while logged into QBO): Ctrl+Alt+? (Windows) or Control+Option+? (Mac) — shows Company ID on screen
Settings page: Gear icon → Subscriptions and billing → Company ID is at the top
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