quickbooks-mcp-server

QuickBooks MCP Server

<!-- mcp-name: io.github.NyxToolsDev/quickbooks-mcp-server -->

Connect Claude Desktop and Claude Code to QuickBooks Online for natural-language accounting. Ask questions about invoices, expenses, reports, and more using plain English.

 

---

What is this?

An MCP (Model Context Protocol) server that gives Claude direct access to your QuickBooks Online data. Instead of logging into QuickBooks and clicking through reports, just ask Claude:

"Show me all overdue invoices sorted by amount" "What's our P&L this quarter?" "Create an invoice for Acme Corp for $2,500"

The server handles OAuth authentication, API calls, rate limiting, and data formatting.

---

Quick Start

1. Install

pip install quickbooks-mcp

Or install from source:

git clone https://github.com/nyxtools/quickbooks-mcp-server.git
cd quickbooks-mcp-server
pip install -e .

2. Create a QuickBooks Developer App

1. Go to developer.intuit.com
2. Create an app and select QuickBooks Online and Payments
3. Under Keys & OAuth, note your Client ID and Client Secret
4. Add http://localhost:8080/callback as a Redirect URI

3. Set Environment Variables

export QBO_CLIENT_ID='your_client_id'
export QBO_CLIENT_SECRET='your_client_secret'

4. Run OAuth Setup

python scripts/setup_oauth.py

This opens your browser, authorizes with QuickBooks, and stores tokens locally (encrypted). Note the Realm ID it prints at the end.

export QBO_REALM_ID='your_realm_id'

5. Configure Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "quickbooks": {
      "command": "quickbooks-mcp",
      "env": {
        "QBO_CLIENT_ID": "your_client_id",
        "QBO_CLIENT_SECRET": "your_client_secret",
        "QBO_REALM_ID": "your_realm_id"
      }
    }
  }
}

Config file locations:

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

6. Start Using It

Restart Claude Desktop and try: > "What are my current bank account balances?"

---

All 19 Tools

Free Tier (9 tools)

| Tool | Description | |------|-------------| | list_invoices | List and filter invoices by status, date, customer | | get_invoice_details | Full invoice details with line items and payment history | | get_overdue_invoices | All overdue invoices sorted by days past due | | list_expenses | List expenses with date, vendor, amount, and category filters | | get_top_expenses | Top expenses grouped by category or vendor for any period | | get_account_balances | Current balances for Bank, Credit Card, or all accounts | | get_account_transactions | Recent transactions for any account with date filters | | search_customers | Search customers by name or email with contact info | | get_customer_summary | Customer financial summary: invoiced, paid, outstanding |

Premium Tier (10 tools) -- $29/month

| Tool | Description | |------|-------------| | get_profit_and_loss | P&L report for any period with income/expense breakdown | | get_balance_sheet | Balance sheet as of any date (assets, liabilities, equity) | | get_cash_flow | Cash flow statement (operating, investing, financing) | | get_accounts_receivable_aging | AR aging by customer (current/30/60/90+ days) | | get_accounts_payable_aging | AP aging by vendor (current/30/60/90+ days) | | create_invoice | Create invoices with line items, due dates, and memos | | record_payment | Record payments against invoices with method and reference | | create_expense | Record expenses with vendor, amount, category, and date | | get_financial_health | Key ratios: current ratio, DSO, burn rate, runway | | compare_periods | Side-by-side period comparison with % changes |

Get a premium license at nyxtools.dev/quickbooks-mcp

Set it in your environment: ``bash export LICENSE_KEY='your_license_key' ``

---

Usage Examples

Invoices

"Show me all invoices from January" "Which invoices are overdue? Show me the worst ones first" "Get the details for invoice #1042" "Show me open invoices for Acme Corp"

Expenses

"What did we spend this month?" "Show me our top 10 expense categories this quarter" "How much have we spent at Amazon this year?"

Accounts

"What are our bank balances?" "Show me the last 20 transactions in checking" "What's the balance on our company credit card?"

Customers

"Find the customer John Smith" "Give me a financial summary for customer 456" "Search for customers with outstanding balances"

Reports (Premium)

"Show me the P&L for this quarter" "Pull up the balance sheet" "How's our cash flow this month?" "Show me the AR aging report" "Who are our slowest-paying customers?"

Write Operations (Premium)

"Create an invoice for customer 123: Website Design $2,500, Hosting $150/month, due net-30" "Record a $1,000 check payment on invoice #1042" "Record a $250 expense to Office Depot for supplies, paid by credit card on March 15"

Analytics (Premium)

"How healthy are our finances? Show me key ratios" "Compare this month to last month" "How did this quarter compare to the same quarter last year?"

---

Configuration

All configuration is via environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | QBO_CLIENT_ID | Yes | | QuickBooks OAuth2 Client ID | | QBO_CLIENT_SECRET | Yes | | QuickBooks OAuth2 Client Secret | | QBO_REALM_ID | Yes | | QuickBooks Company/Realm ID | | QBO_REDIRECT_URI | No | http://localhost:8080/callback | OAuth redirect URI | | LICENSE_KEY | No | | Premium license key | | QBO_SANDBOX | No | false | Use sandbox environment | | TOKEN_STORE_PATH | No | ~/.quickbooks-mcp/tokens.json | Token storage location | | LOG_LEVEL | No | INFO | Logging level |

---

Security

• Tokens encrypted at rest using machine-specific keys (Fernet + PBKDF2)
• Tokens auto-refresh -- access tokens last 60 min, refresh tokens 100 days
• No credentials stored in code -- all secrets via environment variables
• Rate limiting built in to respect QuickBooks API throttles
• Input sanitization on all query parameters to prevent injection

---

Development

# Clone and install with dev dependencies
git clone https://github.com/nyxtools/quickbooks-mcp-server.git
cd quickbooks-mcp-server
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=quickbooks_mcp

# Lint
ruff check src/ tests/

# Type check
mypy src/

Project Structure

quickbooks-mcp-server/
  src/quickbooks_mcp/
    auth/          # OAuth2 flow and encrypted token storage
    client/        # QBO REST API client with rate limiting
    tools/         # MCP tool implementations (19 tools)
    utils/         # Money (Decimal), formatting, license validation
    server.py      # MCP server setup and tool registration
    config.py      # Environment-based configuration
  scripts/
    setup_oauth.py # Interactive OAuth setup
  examples/        # Config examples and usage guide
  tests/           # Pytest test suite

---

Troubleshooting

"No QuickBooks tokens found"

Run the OAuth setup: ``bash python scripts/setup_oauth.py ``

"Token refresh failed"

Your refresh token may have expired. Re-run OAuth setup.

"QuickBooks API error (HTTP 403)"

Verify your app has com.intuit.quickbooks.accounting scope.

"Rate limited by QuickBooks"

The server handles rate limiting automatically. If you see this error, wait 60 seconds.

"This is a premium feature"

Some tools require a license key. Get one here or set LICENSE_KEY in your environment.

Sandbox Mode

For testing without affecting real data: ``bash export QBO_SANDBOX=true `` Use your Development keys (not Production) from the Intuit developer dashboard.

---

License

MIT License. See LICENSE for details.

Copyright (c) 2026 NyxTools