@mindstone/mcp-server-quickbooks

@mindstone/mcp-server-quickbooks

QuickBooks Online MCP server for Model Context Protocol hosts. Manage invoices, bills, customers, vendors, employees, and accounts in QuickBooks Online through a standardised MCP interface.

Status

• Version: 0.4.0 · npm
• Auth: OAuth (QUICKBOOKS_REFRESH_TOKEN)
• Tools: 21 (customers, vendors, invoices, bills, estimates, reports)
• Surface: cloud-api
• Machine-readable: STATUS.json

⚠️ Breaking change in 0.3.0 — production writes are gated by default

Starting with version 0.3.0, every QuickBooks-mutating tool (create_quickbooks_invoice, create_quickbooks_bill, create_quickbooks_customer, create_quickbooks_vendor, create_quickbooks_estimate, send_quickbooks_invoice_email, update_quickbooks_invoice, update_quickbooks_customer, update_quickbooks_vendor) is secure-by-default: the tool refuses to execute and returns a structured error unless the host sets QB_ALLOW_PROD_WRITES=1 in the environment. Read-only tools (list_*, get_*, query_*, download_*, configure_quickbooks) are unaffected.

This is a deliberate guard-rail to prevent an LLM agent from accidentally writing to a real QuickBooks production company. Hosts that have integrated 0.2.x and rely on those mutating tools must opt in by setting the environment variable on the next upgrade.

Migration from 0.2.x → 0.3.0

To preserve the previous (write-enabled) behaviour, add QB_ALLOW_PROD_WRITES=1 to the env block of your host configuration alongside the existing QUICKBOOKS_* variables. Without it, the mutating tools will return:

{
  "ok": false,
  "error": "QuickBooks mutating tools refuse to run unless QB_ALLOW_PROD_WRITES=1 is set. ...",
  "code": "QB_ALLOW_PROD_WRITES_REQUIRED"
}

We strongly recommend keeping the gate closed in any host where the LLM should not be able to issue production writes (sandbox, staging, demo, or read-only analyst workflows). Set the variable only in environments where QuickBooks writes are an intentional capability.

Requirements

• Node.js 20+
• npm

One-click install

After clicking the button, your host will prompt you to fill: QUICKBOOKS_CLIENT_ID, QUICKBOOKS_CLIENT_SECRET, QUICKBOOKS_REFRESH_TOKEN, QUICKBOOKS_REALM_ID, QUICKBOOKS_ENVIRONMENT.

Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (QuickBooks Online)

{
  "mcpServers": {
    "QuickBooks Online": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-quickbooks"
      ],
      "env": {
        "QUICKBOOKS_CLIENT_ID": "",
        "QUICKBOOKS_CLIENT_SECRET": "",
        "QUICKBOOKS_REFRESH_TOKEN": "",
        "QUICKBOOKS_REALM_ID": "",
        "QUICKBOOKS_ENVIRONMENT": "production"
      }
    }
  }
}

Quick Start

Install & build

cd <path-to-repo>/connectors/quickbooks
npm install
npm run build

npx (once published)

npx -y @mindstone/mcp-server-quickbooks

Local

node dist/index.js

Configuration

Environment variables

• QUICKBOOKS_CLIENT_ID — Intuit Developer app client ID
• QUICKBOOKS_CLIENT_SECRET — Intuit Developer app client secret
• QUICKBOOKS_REFRESH_TOKEN — OAuth 2.0 refresh token
• QUICKBOOKS_REALM_ID — QuickBooks company (realm) ID
• QUICKBOOKS_ENVIRONMENT — sandbox or production (default: production)
• QB_ALLOW_PROD_WRITES — set to exactly 1 to enable the mutating tools (every create_*, update_*, and send_quickbooks_invoice_email). Any other value (unset, empty, true, yes, 0, …) keeps the secure-by-default gate closed and the mutating tools refuse to run. Read-only tools are unaffected. Required since 0.3.0 to preserve 0.2.x write behaviour.
• MCP_HOST_BRIDGE_STATE — optional path to a host bridge state file used for credential management
• MINDSTONE_REBEL_BRIDGE_STATE — backwards-compatible alias for MCP_HOST_BRIDGE_STATE

Host configuration examples

Claude Desktop / Cursor

{
  "mcpServers": {
    "QuickBooks": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-quickbooks"],
      "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"
      }
    }
  }
}

Local development (no npm publish needed)

{
  "mcpServers": {
    "QuickBooks": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/quickbooks/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"
      }
    }
  }
}

Tools (21)

Configuration

• configure_quickbooks — Configure QuickBooks Online OAuth credentials

Query

• query_quickbooks — Run a QuickBooks query using QuickBooks Query Language
• get_quickbooks_entity — Get a single entity by type and ID

Reports

• get_quickbooks_report — Run a financial report (ProfitAndLoss, BalanceSheet, CashFlow, AgedReceivables, AgedPayables)

Customers

• list_quickbooks_customers — List customers
• create_quickbooks_customer — Create a new customer
• update_quickbooks_customer — Sparse-update a customer (deactivate with active: false)

Vendors

• list_quickbooks_vendors — List vendors
• create_quickbooks_vendor — Create a new vendor
• update_quickbooks_vendor — Sparse-update a vendor (deactivate with active: false)

Invoices

• list_quickbooks_invoices — List invoices
• create_quickbooks_invoice — Create a new invoice
• update_quickbooks_invoice — Sparse-update invoice header fields (dueDate, memo, privateNote)
• send_quickbooks_invoice_email — Email an invoice to its customer
• download_quickbooks_invoice_pdf — Download an invoice as a PDF (saved to the system temp directory)

Estimates

• list_quickbooks_estimates — List estimates (quotes)
• create_quickbooks_estimate — Create a new estimate

Bills

• list_quickbooks_bills — List bills (accounts payable)
• create_quickbooks_bill — Create a new bill

Employees

• list_quickbooks_employees — List employees

Accounts

• list_quickbooks_accounts — List chart of accounts

Untrusted content envelopes

Text authored inside QuickBooks (customer/vendor display names, memos, line descriptions, report cells) is attacker-influenceable, so the connector wraps it in <untrusted-content source="quickbooks:…"> envelopes before returning it to the model. Typed entity payloads are sanitized deny-by-default: every string is enveloped — including strings inside arrays, which have no key context — unless its key is a narrow structural predicate (IDs, SyncToken, dates/timestamps, enums) and its value passes a shape guard. query_quickbooks, get_quickbooks_entity, and reports envelope every string key and value wholesale. Structural values such as Id, SyncToken, dates, and amounts are left untouched so they stay usable as inputs to follow-up calls.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.