What can you do with this server?

This QuickBooks Online MCP Server provides comprehensive accounting and business management through 144 tools covering 29 entity types and 11 financial reports, with full CRUD (Create, Read, Update, Delete, Search) operations. Customer & Sales Management * Customers: Create, read, update, delete, and search * Invoices: Create, read, update, void, and search with line items * Estimates: Create, read, update, void, and search * Payments: Record, retrieve, update, void, and search customer payments * Sales Receipts, Credit Memos, Refund Receipts: Full CRUD and search Vendor & Purchasing * Vendors: Create, read, update, deactivate, and search * Bills & Bill Payments: Create, read, update, delete, and search * Purchase Orders & Vendor Credits: Create, read, update, delete, and search * Purchases: Create, read, update, delete, and search Banking & Accounting * Chart of Accounts: Create, read, update, and search * Deposits & Transfers: Create, read, update, delete, and search * Journal Entries: Create, read, update, delete, and search Employees & Time Tracking * Employees: Create, read, update, delete, and search * Time Activities: Create, read, update, delete, and search (with billable status) Items, Classification & Settings * Items: Create, read, update, delete, and search products/services * Classes & Departments: Create, read, update, and search * Terms & Payment Methods: Create, read, update, and search * Tax Codes, Tax Rates, Tax Agencies: Read and search * Company Info: Read and update; Attachments: Full CRUD and search Financial Reports * Balance Sheet, Profit & Loss, Cash Flow, Trial Balance, General Ledger, Customer Sales, Aged Receivables (summary & detail), Customer Balance, Aged Payables, Vendor Expenses Additional Capabilities * Multi-company support: Target specific companies via realm ID on any tool call, list available companies, and run as a remote HTTP multi-tenant server * OAuth 2.0 authentication with sandbox and production support, and automatic token refresh * Configurable permissions: Optionally disable write, update, or delete tool categories for security * Built with TypeScript and Zod validation for type safety

Which integrations are available for this server?

Provides full CRUD operations for 29 entity types (customers, invoices, bills, vendors, etc.) and access to 11 financial reports (balance sheet, profit & loss, cash flow, etc.) via the QuickBooks Online API.

How do I use QuickBooks Online MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@QuickBooks Online MCP Server Show me the profit and loss report for last month." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

QuickBooks Online MCP Server

by Brax-Tech-Internal

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

This QuickBooks Online MCP Server provides comprehensive accounting and business management through 144 tools covering 29 entity types and 11 financial reports, with full CRUD (Create, Read, Update, Delete, Search) operations.

Customer & Sales Management

Customers: Create, read, update, delete, and search
Invoices: Create, read, update, void, and search with line items
Estimates: Create, read, update, void, and search
Payments: Record, retrieve, update, void, and search customer payments
Sales Receipts, Credit Memos, Refund Receipts: Full CRUD and search

Vendor & Purchasing

Vendors: Create, read, update, deactivate, and search
Bills & Bill Payments: Create, read, update, delete, and search
Purchase Orders & Vendor Credits: Create, read, update, delete, and search
Purchases: Create, read, update, delete, and search

Banking & Accounting

Chart of Accounts: Create, read, update, and search
Deposits & Transfers: Create, read, update, delete, and search
Journal Entries: Create, read, update, delete, and search

Employees & Time Tracking

Employees: Create, read, update, delete, and search
Time Activities: Create, read, update, delete, and search (with billable status)

Items, Classification & Settings

Items: Create, read, update, delete, and search products/services
Classes & Departments: Create, read, update, and search
Terms & Payment Methods: Create, read, update, and search
Tax Codes, Tax Rates, Tax Agencies: Read and search
Company Info: Read and update; Attachments: Full CRUD and search

Financial Reports

Balance Sheet, Profit & Loss, Cash Flow, Trial Balance, General Ledger, Customer Sales, Aged Receivables (summary & detail), Customer Balance, Aged Payables, Vendor Expenses

Additional Capabilities

Multi-company support: Target specific companies via realm ID on any tool call, list available companies, and run as a remote HTTP multi-tenant server
OAuth 2.0 authentication with sandbox and production support, and automatic token refresh
Configurable permissions: Optionally disable write, update, or delete tool categories for security
Built with TypeScript and Zod validation for type safety

QuickBooks Online MCP Server

A comprehensive Model Context Protocol (MCP) server for QuickBooks Online

Quick Start | Available Tools | Authentication | Documentation

Overview

This MCP server provides complete QuickBooks Online API integration for Claude Code and other MCP-compatible clients. It includes full CRUD operations for 29 entity types and 11 financial reports, giving you comprehensive access to QuickBooks Online functionality.

Key Features

144 Total Tools - Complete coverage of QuickBooks Online API
29 Entity Types - Full CRUD operations (Create, Read, Update, Delete, Search)
11 Financial Reports - Balance Sheet, P&L, Cash Flow, and more
OAuth 2.0 Authentication - Secure token-based authentication
TypeScript - Full type safety with Zod validation
Tested - Jest test suite with ESM support

Note: this is a local MCP server. It runs as a stdio subprocess on the developer's or partner's machine and authenticates to a QuickBooks Online company.

Related MCP server: QuickBooks Online MCP Server

Quick Start

Installation

# Clone the repository
git clone https://github.com/your-username/mcp-quickbooks-online.git
cd mcp-quickbooks-online

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Copy the template .env.example to .env in the root directory and fill in your values:

cp .env.example .env

QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_ENVIRONMENT=sandbox
QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
QUICKBOOKS_REALM_ID=your_realm_id

# Optional: restrict which tool categories are registered (default: all enabled)
# QUICKBOOKS_DISABLE_WRITE=true    # suppress create_* tools
# QUICKBOOKS_DISABLE_UPDATE=true   # suppress update_* tools
# QUICKBOOKS_DISABLE_DELETE=true   # suppress delete_* tools

.env is gitignored so your real credentials stay local.

Claude Code Integration

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["path/to/mcp-quickbooks-online/dist/index.js"],
      "env": {
        "QUICKBOOKS_CLIENT_ID": "your_client_id",
        "QUICKBOOKS_CLIENT_SECRET": "your_client_secret",
        "QUICKBOOKS_REFRESH_TOKEN": "your_refresh_token",
        "QUICKBOOKS_REALM_ID": "your_realm_id",
        "QUICKBOOKS_ENVIRONMENT": "sandbox",
        "QUICKBOOKS_DISABLE_WRITE": "false",
        "QUICKBOOKS_DISABLE_UPDATE": "false",
        "QUICKBOOKS_DISABLE_DELETE": "false"
      }
    }
  }
}

Set any of the DISABLE_* flags to "true" to prevent that category of tools from being registered. Read tools (get_*, search_*) are always available.

Multi-company & remote deployment

The server can also run as a remote, multi-company HTTP MCP server. One Intuit app authorizes many QuickBooks companies via built-in OAuth onboarding; each company is reached at /mcp/<realmId> and guarded by a shared bearer token. Refresh tokens persist per-company in a data volume.

Set MCP_TRANSPORT=http (or PORT) to start the HTTP server instead of stdio.
Onboard companies at GET /connect?token=<MCP_BEARER_TOKEN> (OAuth); list them at GET /companies; health at GET /health.
App-level env: QBO_CLIENT_ID, QBO_CLIENT_SECRET, QBO_ENVIRONMENT, PUBLIC_BASE_URL, MCP_BEARER_TOKEN (legacy QUICKBOOKS_* names still work for single-company stdio).
Ships with a Dockerfile and docker-compose.yml (with a Cloudflare cloudflared named-tunnel sidecar).

Two ways to target a company:

Per-connection — connect to /mcp/<realmId>; every call uses that company. (Strong isolation, natural per-company auth; N companies = N × tools in the client.)
Single connection — connect to /mcp (no realm) and pass an optional company (realm ID) argument on each tool call. One connection serves every company with a constant ~140 tools. The company field is injected centrally in RegisterTool, so no handler needs it; if omitted, the connection's default company is used.

How it works (architecture)

One Intuit app → many companies. Each OAuth authorization yields a distinct realmId + refresh token; tokens persist per-company in a data volume (data/companies.json).
Company context via AsyncLocalStorage. Every request is bound to a company; the static QuickbooksClient.getInstance() resolves the current realm from context and returns a per-company client from a registry — so none of the ~90 handlers need changes. (src/clients/company-context.ts, src/clients/quickbooks-client.ts.)
Two ways to select a company (see table above): per-connection URL, or an optional company argument injected into every tool by src/helpers/register-tool.ts.
Security layers: Cloudflare named tunnel (no inbound ports) → Cloudflare Access → app auth. Two front doors hit the same server: a service-token + bearer path for header-capable/machine clients, and a separate Managed-OAuth hostname so Claude Desktop / claude.ai can add it as a one-click OAuth custom connector (no headers — browser SSO + Dynamic Client Registration at the edge).
Admin UI at / (→ /admin, Gmail SSO) to OAuth-onboard companies, view live details, test/refresh, and disconnect.
list_companies tool lets a connected client enumerate the realms it can act on, then pass one as the company argument.

Documentation

Guide	What it covers
DEPLOY.md	Docker + Cloudflare named-tunnel deployment, OAuth onboarding, env vars
docs/CONNECTING-CLIENTS.md	Adding the server to Claude Code, Claude Desktop, Claude.ai/Cowork, OpenAI Codex, Cursor, VS Code

Quick add (Claude Code, single-connection mode — pass company per call):

claude mcp add --transport http qbo https://<PUBLIC_BASE_URL>/mcp \
  --header "CF-Access-Client-Id: <CF_ACCESS_CLIENT_ID>" \
  --header "CF-Access-Client-Secret: <CF_ACCESS_CLIENT_SECRET>" \
  --header "Authorization: Bearer <MCP_BEARER_TOKEN>"

Available Tools

Entities

Complete CRUD operations are available for all entity types:

Entity	Create	Get	Update	Delete	Search
Customer	✅	✅	✅	✅	✅
Invoice	✅	✅	✅	✅	✅
Estimate	✅	✅	✅	✅	✅
Bill	✅	✅	✅	✅	✅
Vendor	✅	✅	✅	✅	✅
Employee	✅	✅	✅	✅	✅
Account	✅	✅	✅	-	✅
Item	✅	✅	✅	✅	✅
Journal Entry	✅	✅	✅	✅	✅
Bill Payment	✅	✅	✅	✅	✅
Purchase	✅	✅	✅	✅	✅
Payment	✅	✅	✅	✅	✅
Sales Receipt	✅	✅	✅	✅	✅
Credit Memo	✅	✅	✅	✅	✅
Refund Receipt	✅	✅	✅	✅	✅
Purchase Order	✅	✅	✅	✅	✅
Vendor Credit	✅	✅	✅	✅	✅
Deposit	✅	✅	✅	✅	✅
Transfer	✅	✅	✅	✅	✅
Time Activity	✅	✅	✅	✅	✅
Class	✅	✅	✅	-	✅
Department	✅	✅	✅	-	✅
Term	✅	✅	✅	-	✅
Payment Method	✅	✅	✅	-	✅
Tax Code	-	✅	-	-	✅
Tax Rate	-	✅	-	-	✅
Tax Agency	-	✅	-	-	✅
Company Info	-	✅	✅	-	-
Attachable	✅	✅	✅	✅	✅

Reports

Report	Tool Name	Description
Balance Sheet	`get_balance_sheet`	Assets, liabilities, and equity snapshot
Profit & Loss	`get_profit_and_loss`	Income and expenses over a period
Cash Flow	`get_cash_flow`	Cash inflows and outflows
Trial Balance	`get_trial_balance`	Debit and credit balances
General Ledger	`get_general_ledger`	Complete transaction history
Customer Sales	`get_customer_sales`	Sales by customer
Aged Receivables	`get_aged_receivables`	Outstanding customer invoices
Aged Receivables Detail	`get_aged_receivables_detail`	Detailed aging breakdown
Customer Balance	`get_customer_balance`	Current customer balances
Aged Payables	`get_aged_payables`	Outstanding vendor bills
Vendor Expenses	`get_vendor_expenses`	Expenses by vendor

Tool Reference

Tool	Description
`create_customer`	Create a new customer
`get_customer`	Get customer by ID
`update_customer`	Update customer details
`delete_customer`	Delete a customer
`search_customers`	Search customers with filters

Tool	Description
`create_invoice`	Create a new invoice
`get_invoice`	Get invoice by ID
`update_invoice`	Update invoice details
`delete_invoice`	Delete/void an invoice
`search_invoices`	Search invoices with filters

Tool	Description
`create_payment`	Record a customer payment
`get_payment`	Get payment by ID
`update_payment`	Update payment details
`delete_payment`	Void a payment
`search_payments`	Search payments with filters

Tool	Description
`create_bill`	Create a new bill
`get_bill`	Get bill by ID
`update_bill`	Update bill details
`delete_bill`	Delete a bill
`search_bills`	Search bills with filters
`create_vendor`	Create a new vendor
`get_vendor`	Get vendor by ID
`update_vendor`	Update vendor details
`delete_vendor`	Delete a vendor
`search_vendors`	Search vendors with filters
`create_bill_payment`	Create a bill payment
`get_bill_payment`	Get bill payment by ID
`update_bill_payment`	Update bill payment
`delete_bill_payment`	Delete a bill payment
`search_bill_payments`	Search bill payments

Tool	Description
`create_sales_receipt`	Create a sales receipt
`get_sales_receipt`	Get sales receipt by ID
`update_sales_receipt`	Update sales receipt
`delete_sales_receipt`	Void a sales receipt
`search_sales_receipts`	Search sales receipts
`create_credit_memo`	Create a credit memo
`get_credit_memo`	Get credit memo by ID
`update_credit_memo`	Update credit memo
`delete_credit_memo`	Void a credit memo
`search_credit_memos`	Search credit memos
`create_refund_receipt`	Create a refund receipt
`get_refund_receipt`	Get refund receipt by ID
`update_refund_receipt`	Update refund receipt
`delete_refund_receipt`	Void a refund receipt
`search_refund_receipts`	Search refund receipts

Tool	Description
`create_deposit`	Create a bank deposit
`get_deposit`	Get deposit by ID
`update_deposit`	Update deposit details
`delete_deposit`	Delete a deposit
`search_deposits`	Search deposits
`create_transfer`	Create an account transfer
`get_transfer`	Get transfer by ID
`update_transfer`	Update transfer details
`delete_transfer`	Delete a transfer
`search_transfers`	Search transfers

Tool	Description
`create_purchase_order`	Create a purchase order
`get_purchase_order`	Get purchase order by ID
`update_purchase_order`	Update purchase order
`delete_purchase_order`	Delete a purchase order
`search_purchase_orders`	Search purchase orders
`create_vendor_credit`	Create a vendor credit
`get_vendor_credit`	Get vendor credit by ID
`update_vendor_credit`	Update vendor credit
`delete_vendor_credit`	Delete a vendor credit
`search_vendor_credits`	Search vendor credits

Tool	Description
`create_time_activity`	Create a time activity
`get_time_activity`	Get time activity by ID
`update_time_activity`	Update time activity
`delete_time_activity`	Delete a time activity
`search_time_activities`	Search time activities

Tool	Description
`create_class`	Create a class
`get_class`	Get class by ID
`update_class`	Update class details
`search_classes`	Search classes
`create_department`	Create a department
`get_department`	Get department by ID
`update_department`	Update department
`search_departments`	Search departments

Tool	Description
`create_term`	Create a payment term
`get_term`	Get term by ID
`update_term`	Update term details
`search_terms`	Search terms
`create_payment_method`	Create a payment method
`get_payment_method`	Get payment method by ID
`update_payment_method`	Update payment method
`search_payment_methods`	Search payment methods

Tool	Description
`get_tax_code`	Get tax code by ID
`search_tax_codes`	Search tax codes
`get_tax_rate`	Get tax rate by ID
`search_tax_rates`	Search tax rates
`get_tax_agency`	Get tax agency by ID
`search_tax_agencies`	Search tax agencies

Tool	Description
`get_company_info`	Get company information
`update_company_info`	Update company info
`create_attachable`	Create an attachment
`get_attachable`	Get attachment by ID
`update_attachable`	Update attachment
`delete_attachable`	Delete an attachment
`search_attachables`	Search attachments

Authentication

This server uses OAuth 2.0 to authenticate to a QuickBooks Online company. You'll set up an app on the Intuit Developer Portal and connect it to either a sandbox (for development) or your production QBO company.

Important: Sandbox vs Production

Mode	When to use	Redirect URI accepted	Setup difficulty
Sandbox	Development, testing, demos	`http://localhost:8000/callback` works	Easy
Production	Real company data	Localhost rejected — must be a public HTTPS URL	Harder (see below)

If you only want to read your own company's data, you still need to set up an app — Intuit does not offer per-user API keys. There is no shortcut around the OAuth + app-creation flow.

Sandbox Setup (recommended for first run)

Go to the Intuit Developer Portal and create a new app
Open the app → Settings (left sidebar) → Redirect URIs → add: http://localhost:8000/callback
Get your Client ID and Client Secret from the app's Keys & Credentials page (Development keys)
Create or use a sandbox company under the Sandbox top-level menu item in the dev portal
Set QUICKBOOKS_ENVIRONMENT=sandbox in your .env
Run npm run auth to complete the OAuth handshake — your browser will open, you sign in to the sandbox company, tokens are saved to .env

Production Setup

The Intuit Developer Portal rejects http://localhost redirect URIs in production mode — every contributor hits this. Two known workarounds:

ngrok tunnel (most common): run ngrok http 8000, then on your Intuit app go to Settings → Redirect URIs and add the generated https://<id>.ngrok-free.app/callback URL. Use that URL for the OAuth handshake, then revert to localhost afterwards.
Deploy a small public callback handler (e.g., on a VPS or serverless function) that captures the auth code and hands it back to your local setup. More involved; only needed if you can't use ngrok.

After completing the production OAuth handshake, the refresh token is what matters — once it's in .env, you no longer need the public redirect URL for day-to-day use. Refresh tokens auto-rotate; the server persists the new token on each refresh.

Once you have tokens

QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
QUICKBOOKS_REALM_ID=your_realm_id
QUICKBOOKS_ENVIRONMENT=sandbox  # or 'production'

Common pitfalls

.env loaded from the wrong directory. The server resolves .env relative to the compiled module, not your shell's CWD. If you launch via Claude Desktop, this matters — make sure you're on current main.
Redirect URI mismatch. The URI you register in the Intuit portal must match exactly — protocol, host, port, path. http://localhost:8000/callback .

Development

Building

npm run build

Testing

npm test

The test suite includes 396 tests with 100% code coverage across all metrics (statements, branches, functions, lines).

Project Structure

src/
├── clients/          # QuickBooks API client
├── handlers/         # Business logic handlers (87 files)
├── tools/           # MCP tool definitions
├── helpers/         # Utility functions
├── types/           # TypeScript types
└── index.ts         # Server entry point

tests/
├── unit/            # Unit tests (396 tests)
│   ├── handlers/    # Handler tests (15 test files)
│   └── helpers/     # Helper tests
└── mocks/           # Test mocks

docs/
├── ARCHITECTURE.md  # System architecture & design patterns
├── TESTING.md       # Testing guide & patterns
└── plans/           # Development plans

Documentation

Document	Description
CHANGELOG.md	Version history and all changes
docs/ARCHITECTURE.md	System architecture, patterns, and design decisions
docs/TESTING.md	Testing strategy, ESM patterns, and coverage guide

Error Handling

If you encounter connection errors:

Verify all environment variables are set correctly
Check that tokens are valid and not expired
Ensure the QuickBooks app has the correct redirect URIs
For sandbox testing, use QUICKBOOKS_ENVIRONMENT=sandbox

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Tool naming convention

All tool names must follow the {verb}_{entity} convention using underscores. The verb prefix determines CRUD Restriction Mode behaviour:

Prefix	Category	Suppressed by
`create_`	WRITE	`QUICKBOOKS_DISABLE_WRITE=true`
`update_`	UPDATE	`QUICKBOOKS_DISABLE_UPDATE=true`
`delete_`	DELETE	`QUICKBOOKS_DISABLE_DELETE=true`
`get_`, `search_`, `read_`	READ	never

New tools that do not follow this convention will not be correctly categorised and may appear or be suppressed unexpectedly.

License

MIT License - see LICENSE for details.

Acknowledgments

Based on Intuit's QuickBooks Online MCP Server
Built with the Model Context Protocol