Quickbooks MCP Server

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)

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

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:

---

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