AccountingQB-MCP

The most comprehensive QuickBooks Online MCP server for Claude. Built for sole proprietors and small businesses who want to manage their books, run reports, and prep taxes through natural conversation.

119 tools covering transactions, reports, tax prep (US and Canada), reconciliation, smart bookkeeping, 1099/T4A reporting, GST/HST returns, anomaly detection, credit memos, vendor credits, cash flow forecasting, and profit margin analysis — all from Claude Desktop. Includes a CPA Workbook: a 15-page year-end binder (comparative statements, reconciliation tie-outs, tax payments made, owner's draws, tax organizer) exported to Excel for your accountant.

Canada support: works with Canadian QuickBooks Online companies out of the box — the server auto-detects the company's tax edition, applies sales tax codes (GST/HST/PST) on created transactions, and ships a full Canadian tax suite: GST/HST (GST34) return workpapers with the 50% meals ITC restriction, T2125 line mapping, CCA schedules (half-year rule + Accelerated Investment Incentive), T4A/T5018 contractor reporting, and CRA instalment + CPP estimates. Multicurrency companies see per-transaction currency and exchange rates.

Built by Vaspera Capital — because QuickBooks deserved a real MCP server.

Quick Start

Prerequisites

• Python 3.10+
• A QuickBooks Online account (any plan)
• Claude Desktop
• An Intuit Developer account (free signup)

1. Clone and Install

git clone https://github.com/RCOLKITT/AccountingQB-MCP.git
cd AccountingQB-MCP
pip install -r requirements.txt

2. Create Your Intuit Developer App

1. Go to developer.intuit.com and sign in
2. Click Create an App → select QuickBooks Online and Payments
3. Under Redirect URIs, add: http://localhost:8080/callback
4. Copy your Client ID and Client Secret

3. Run Setup

python setup.py

The setup wizard will:

• Ask for your Client ID and Client Secret
• Open your browser to authorize access to your QuickBooks company
• Catch the OAuth callback automatically
• Write your Claude Desktop configuration
• Verify the connection works

That's it. Restart Claude Desktop and you're connected.

Manual Configuration (Advanced)

If you prefer to configure manually, add this to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "accountingqb": {
      "command": "python3",
      "args": ["/path/to/AccountingQB-MCP/server.py"],
      "env": {
        "QB_CLIENT_ID": "your_client_id",
        "QB_CLIENT_SECRET": "your_client_secret",
        "QB_REALM_ID": "your_company_id",
        "QB_REFRESH_TOKEN": "your_refresh_token",
        "QB_ENVIRONMENT": "production"
      }
    }
  }
}

To get your refresh token manually, use the Intuit OAuth Playground.

Tools (113)

Company & Entities

Transactions

Create & Modify

Reports & Analysis

Tax Preparation

Canadian Tax (GST/HST, T2125)

Smart Features

Reconciliation & Attachments

Connection & Multi-Company

Usage Examples

Once connected, just ask Claude naturally:

• "What's my P&L for 2025?"
• "Show me all expenses over $500 from last month"
• "Create an expense for $49.99 to GitHub for software subscriptions"
• "Run my Schedule C for tax year 2025"
• "Find any uncategorized transactions"
• "What's my monthly burn rate?"
• "How much runway do I have?"
• "Compare Q1 vs Q2 profit and loss"
• "Find potential duplicate transactions"
• "What deductions am I missing?"
• "Generate my 1099 contractor report"
• "Run anomaly detection on last quarter's transactions"
• "Show my profit margins by customer"
• "Forecast my cash flow for the next 6 months"
• "Create a vendor credit for $200 to Amazon"
• "Convert estimate #1042 to an invoice"
• "Build my GST/HST return workpaper for Q2" (Canada)
• "Map my books to the T2125 and estimate my CRA instalments" (Canada)

Security

This server takes security seriously:

• No credentials in code — all secrets come from environment variables
• OAuth 2.0 with automatic token rotation
• Local-only OAuth flow — the setup script runs a callback server on 127.0.0.1
• .env files are gitignored and set to chmod 600 (owner-only)
• No data storage — the server is stateless; it reads/writes to QuickBooks and nothing else
• Refresh tokens rotate — each token exchange returns a new refresh token
• 100-day expiry — tokens expire after 100 days of inactivity (Intuit policy)

Token Management

QuickBooks refresh tokens are valid for 100 days and rotate automatically on every use, so an active connection stays live indefinitely. If a connection does lapse (100+ days idle), reconnect based on how you run AccountingQB:

• Hosted / managed (you have a license key): In Claude, run qb_refresh_connection first — it silently re-establishes most expired connections with no browser step. If the connection is fully gone, reconnect at accountingqb.com/dashboard → Connect QuickBooks, then run qb_refresh_connection again.
• Self-hosted (your own Intuit app): re-run python setup.py to re-authorize and rewrite your refresh token.

Sandbox Mode

Test with Intuit's sandbox before connecting to production:

python setup.py --sandbox

This connects to sandbox-quickbooks.api.intuit.com with Intuit's test data. Switch to production when ready by running setup again without the flag.

Troubleshooting

"QuickBooks credentials not configured" Self-hosted: run python setup.py to configure credentials, or check your Claude Desktop config. Hosted/managed: set your QB_LICENSE_KEY and connect a company at accountingqb.com/dashboard.

"401 Unauthorized" Your connection may have expired (100-day idle limit). Hosted/managed: run qb_refresh_connection first, then if needed reconnect at accountingqb.com/dashboard → Connect QuickBooks. Self-hosted: re-run python setup.py to re-authorize.

"Company not found" Check that your QB_REALM_ID matches the company you authorized. You can find it in the URL when logged into QuickBooks Online.

Tools not appearing in Claude Desktop Restart Claude Desktop after running setup. Check that the accountingqb entry exists in your Claude Desktop config.

Sandbox vs Production If you're seeing test data, check that QB_ENVIRONMENT is set to "production" in your config.

Contributing

Issues and PRs welcome. If you're adding new tools, follow the existing pattern:

• Use flat parameters (not Pydantic models) for Claude Desktop compatibility
• Include descriptive docstrings
• Handle errors gracefully with actionable messages
• Add the tool to the README table

License

Proprietary — © Vaspera Capital LLC, all rights reserved. The source is publicly viewable for transparency and security review; it is not open source. Use requires a paid license key. See LICENSE.

Built by Vaspera Capital