QuickBooks Online MCP Server

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

Quick Start | Available Tools | Authentication | Documentation

Safety model

This server is built for use against real books. It exposes 141 QuickBooks Online tools — or 70 in read-only mode — with two safeguards around them.

1. Mutations pause for a human. Every create_*, update_* and delete_* call surfaces an approval prompt describing what is about to happen in plain English, before it executes:

DELETE invoice on LIVE books.

Id: 1042

Irreversible. Recoverable only via the QuickBooks Audit Log.

2. QuickBooks text is treated as untrusted input. Customer names, invoice memos, private notes and attachment filenames are attacker-influenceable — a counterparty can put text in them. Read responses wrap every string in <untrusted-qbo-data field="KEY"> delimiters so an agent reads them as data rather than instructions, and flags strings matching known injection patterns:

WARNING: INJECTION SUSPECTED in 1 field
  Invoice[0].PrivateNote - matched: instruction-override - "<untrusted-qbo-data field="excerpt">Ignore all previous instructions...</untrusted-qbo-data>"

<untrusted-qbo-data field="PrivateNote">Ignore all previous instructions...</untrusted-qbo-data>

IDs, dates and amounts pass through byte-exact so arithmetic and reconciliation are unaffected.

The two halves fail in deliberately opposite directions. The confirmation gate fails closed — any error produces a prompt, never silent execution. The sanitizer fails open — if it errors it returns the data with a warning, because silently blocking a P&L is worse than the risk it mitigates.

Related MCP server: qbo-mcp

Installing the safeguards — both steps are required

The confirmation gate lives in the Claude Code harness, not in the server. It needs two entries in ~/.claude/settings.json, and the second one is the part that actually matters.

{
  "permissions": {
    "ask": [
      "mcp__qbo-write__create_*", "mcp__qbo-write__update_*", "mcp__qbo-write__delete_*",
      "mcp__qbo-write__create-*", "mcp__qbo-write__update-*", "mcp__qbo-write__delete-*"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__qbo-write__(create|update|delete).*",
        "hooks": [
          { "type": "command", "command": "<absolute path to your clone>/bin/qbo-confirm-hook" }
        ]
      }
    ]
  }
}

Do not skip the permissions.ask rules. A PreToolUse hook is advisory. Claude Code's docs are explicit that "deny and ask rules are evaluated regardless of what a PreToolUse hook returns", and in auto mode a classifier resolves the hook's ask decision without involving you. We found this by watching it happen: two near-identical create_estimate calls in one session, one prompted and one executed silently against production. The ask rule is what guarantees the prompt, in every permission mode. The hook only supplies the human-readable summary shown inside it.

Both separators are needed because six tools use the legacy hyphen form (create-bill, create-vendor, update-bill, update-vendor, delete-bill, delete-vendor).

The matcher is keyed on the MCP server name, so it must match whatever name you register this server under. Registering the same server a second time under a different name silently bypasses the gate.

Read-only by default

Two launch wrappers are provided. Prefer the read-only one for anything that only reads:

Read-only mode is enforced at registration time via QUICKBOOKS_DISABLE_WRITE, QUICKBOOKS_DISABLE_UPDATE and QUICKBOOKS_DISABLE_DELETE, so the write tools are absent from the catalogue rather than merely discouraged.

Both wrappers read the OAuth client secret from the macOS Keychain rather than .env, so anything that merely reads .env gets a refresh token it cannot use.

Honest limitations

• The gate is a prompt, not a policy engine. It stops unattended writes. It does not stop an approved-but-wrong write.

• Amounts shown in the prompt are informational. They are read from the tool payload before the handler transforms it and before QuickBooks computes tax, so they can overstate but should not be relied on as the posted total. Nothing is gated on them — every money document prompts regardless of amount.

• Injection detection is pattern-based, so it will miss novel phrasings. The delimiting is the load-bearing half; the pattern flags are a convenience.

• get_invoice_pdf returns base64 inline by default and skips injection detection for genuine PDF payloads (verified by the %PDF- magic bytes). Hostile text inside a real PDF's content stream is not inspected.

• Only tested on macOS with Claude Code. The hook is a Claude Code integration; other MCP clients get the sanitizer but no confirmation gate.

Test suite: 36 suites, 818 tests, with a 100% coverage gate on src/.

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.

Before you start: This MCP server is easy to run once authenticated, but QuickBooks Online integration is gated by Intuit's OAuth app setup. You must register an app on the Intuit Developer Portal and complete a one-time, browser-based OAuth handshake. Sandbox supports http://localhost redirect URIs; production requires a public HTTPS callback for the initial authorization. After that initial handshake, the server runs locally without further browser interaction (until the 100-day refresh window lapses). See Authentication for full details.

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.

Available Tools

Entities

Complete CRUD operations are available for all entity types:

Reports

Tool Reference

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

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)

1. Go to the Intuit Developer Portal and create a new app

2. Open the app → Settings (left sidebar) → Redirect URIs → add: http://localhost:8000/callback

3. Get your Client ID and Client Secret from the app's Keys & Credentials page (Development keys)

4. Create or use a sandbox company under the Sandbox top-level menu item in the dev portal

5. Set QUICKBOOKS_ENVIRONMENT=sandbox in your .env

6. 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:

1. 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.

2. 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

Error Handling

If you encounter connection errors:

1. Verify all environment variables are set correctly

2. Check that tokens are valid and not expired

3. Ensure the QuickBooks app has the correct redirect URIs

4. 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:

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