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:

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:

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:

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