{
  "markdown": "# QuickBooks MCP Server\n\n<!-- mcp-name: io.github.NyxToolsDev/quickbooks-mcp-server -->\n\nConnect Claude Desktop and Claude Code to QuickBooks Online for natural-language accounting. Ask questions about invoices, expenses, reports, and more using plain English.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n\n---\n\n## What is this?\n\nAn [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives Claude direct access to your QuickBooks Online data. Instead of logging into QuickBooks and clicking through reports, just ask Claude:\n\n> \"Show me all overdue invoices sorted by amount\"\n> \"What's our P&L this quarter?\"\n> \"Create an invoice for Acme Corp for $2,500\"\n\nThe server handles OAuth authentication, API calls, rate limiting, and data formatting.\n\n---\n\n## Quick Start\n\n### 1. Install\n\n```bash\npip install quickbooks-mcp\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/nyxtools/quickbooks-mcp-server.git\ncd quickbooks-mcp-server\npip install -e .\n```\n\n### 2. Create a QuickBooks Developer App\n\n1. Go to [developer.intuit.com](https://developer.intuit.com/)\n2. Create an app and select **QuickBooks Online and Payments**\n3. Under **Keys & OAuth**, note your **Client ID** and **Client Secret**\n4. Add `http://localhost:8080/callback` as a **Redirect URI**\n\n### 3. Set Environment Variables\n\n```bash\nexport QBO_CLIENT_ID='your_client_id'\nexport QBO_CLIENT_SECRET='your_client_secret'\n```\n\n### 4. Run OAuth Setup\n\n```bash\npython scripts/setup_oauth.py\n```\n\nThis opens your browser, authorizes with QuickBooks, and stores tokens locally (encrypted). Note the **Realm ID** it prints at the end.\n\n```bash\nexport QBO_REALM_ID='your_realm_id'\n```\n\n### 5. Configure Claude Desktop\n\nAdd to your Claude Desktop config (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"quickbooks\": {\n      \"command\": \"quickbooks-mcp\",\n      \"env\": {\n        \"QBO_CLIENT_ID\": \"your_client_id\",\n        \"QBO_CLIENT_SECRET\": \"your_client_secret\",\n        \"QBO_REALM_ID\": \"your_realm_id\"\n      }\n    }\n  }\n}\n```\n\n**Config file locations:**\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n### 6. Start Using It\n\nRestart Claude Desktop and try:\n> \"What are my current bank account balances?\"\n\n---\n\n## All 19 Tools\n\n### Free Tier (9 tools)\n\n| Tool | Description |\n|------|-------------|\n| `list_invoices` | List and filter invoices by status, date, customer |\n| `get_invoice_details` | Full invoice details with line items and payment history |\n| `get_overdue_invoices` | All overdue invoices sorted by days past due |\n| `list_expenses` | List expenses with date, vendor, amount, and category filters |\n| `get_top_expenses` | Top expenses grouped by category or vendor for any period |\n| `get_account_balances` | Current balances for Bank, Credit Card, or all accounts |\n| `get_account_transactions` | Recent transactions for any account with date filters |\n| `search_customers` | Search customers by name or email with contact info |\n| `get_customer_summary` | Customer financial summary: invoiced, paid, outstanding |\n\n### Premium Tier (10 tools) -- $29/month\n\n| Tool | Description |\n|------|-------------|\n| `get_profit_and_loss` | P&L report for any period with income/expense breakdown |\n| `get_balance_sheet` | Balance sheet as of any date (assets, liabilities, equity) |\n| `get_cash_flow` | Cash flow statement (operating, investing, financing) |\n| `get_accounts_receivable_aging` | AR aging by customer (current/30/60/90+ days) |\n| `get_accounts_payable_aging` | AP aging by vendor (current/30/60/90+ days) |\n| `create_invoice` | Create invoices with line items, due dates, and memos |\n| `record_payment` | Record payments against invoices with method and reference |\n| `create_expense` | Record expenses with vendor, amount, category, and date |\n| `get_financial_health` | Key ratios: current ratio, DSO, burn rate, runway |\n| `compare_periods` | Side-by-side period comparison with % changes |\n\n**Get a premium license at [nyxtools.dev/quickbooks-mcp](https://nyxtools.dev/quickbooks-mcp)**\n\nSet it in your environment:\n```bash\nexport LICENSE_KEY='your_license_key'\n```\n\n---\n\n## Usage Examples\n\n### Invoices\n> \"Show me all invoices from January\"\n> \"Which invoices are overdue? Show me the worst ones first\"\n> \"Get the details for invoice #1042\"\n> \"Show me open invoices for Acme Corp\"\n\n### Expenses\n> \"What did we spend this month?\"\n> \"Show me our top 10 expense categories this quarter\"\n> \"How much have we spent at Amazon this year?\"\n\n### Accounts\n> \"What are our bank balances?\"\n> \"Show me the last 20 transactions in checking\"\n> \"What's the balance on our company credit card?\"\n\n### Customers\n> \"Find the customer John Smith\"\n> \"Give me a financial summary for customer 456\"\n> \"Search for customers with outstanding balances\"\n\n### Reports (Premium)\n> \"Show me the P&L for this quarter\"\n> \"Pull up the balance sheet\"\n> \"How's our cash flow this month?\"\n> \"Show me the AR aging report\"\n> \"Who are our slowest-paying customers?\"\n\n### Write Operations (Premium)\n> \"Create an invoice for customer 123: Website Design $2,500, Hosting $150/month, due net-30\"\n> \"Record a $1,000 check payment on invoice #1042\"\n> \"Record a $250 expense to Office Depot for supplies, paid by credit card on March 15\"\n\n### Analytics (Premium)\n> \"How healthy are our finances? Show me key ratios\"\n> \"Compare this month to last month\"\n> \"How did this quarter compare to the same quarter last year?\"\n\n---\n\n## Configuration\n\nAll configuration is via environment variables:\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `QBO_CLIENT_ID` | Yes | | QuickBooks OAuth2 Client ID |\n| `QBO_CLIENT_SECRET` | Yes | | QuickBooks OAuth2 Client Secret |\n| `QBO_REALM_ID` | Yes | | QuickBooks Company/Realm ID |\n| `QBO_REDIRECT_URI` | No | `http://localhost:8080/callback` | OAuth redirect URI |\n| `LICENSE_KEY` | No | | Premium license key |\n| `QBO_SANDBOX` | No | `false` | Use sandbox environment |\n| `TOKEN_STORE_PATH` | No | `~/.quickbooks-mcp/tokens.json` | Token storage location |\n| `LOG_LEVEL` | No | `INFO` | Logging level |\n\n---\n\n## Security\n\n- **Tokens encrypted at rest** using machine-specific keys (Fernet + PBKDF2)\n- **Tokens auto-refresh** -- access tokens last 60 min, refresh tokens 100 days\n- **No credentials stored in code** -- all secrets via environment variables\n- **Rate limiting built in** to respect QuickBooks API throttles\n- **Input sanitization** on all query parameters to prevent injection\n\n---\n\n## Development\n\n```bash\n# Clone and install with dev dependencies\ngit clone https://github.com/nyxtools/quickbooks-mcp-server.git\ncd quickbooks-mcp-server\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=quickbooks_mcp\n\n# Lint\nruff check src/ tests/\n\n# Type check\nmypy src/\n```\n\n### Project Structure\n\n```\nquickbooks-mcp-server/\n  src/quickbooks_mcp/\n    auth/          # OAuth2 flow and encrypted token storage\n    client/        # QBO REST API client with rate limiting\n    tools/         # MCP tool implementations (19 tools)\n    utils/         # Money (Decimal), formatting, license validation\n    server.py      # MCP server setup and tool registration\n    config.py      # Environment-based configuration\n  scripts/\n    setup_oauth.py # Interactive OAuth setup\n  examples/        # Config examples and usage guide\n  tests/           # Pytest test suite\n```\n\n---\n\n## Troubleshooting\n\n### \"No QuickBooks tokens found\"\nRun the OAuth setup:\n```bash\npython scripts/setup_oauth.py\n```\n\n### \"Token refresh failed\"\nYour refresh token may have expired. Re-run OAuth setup.\n\n### \"QuickBooks API error (HTTP 403)\"\nVerify your app has `com.intuit.quickbooks.accounting` scope.\n\n### \"Rate limited by QuickBooks\"\nThe server handles rate limiting automatically. If you see this error, wait 60 seconds.\n\n### \"This is a premium feature\"\nSome tools require a license key. [Get one here](https://nyxtools.dev/quickbooks-mcp) or set `LICENSE_KEY` in your environment.\n\n### Sandbox Mode\nFor testing without affecting real data:\n```bash\nexport QBO_SANDBOX=true\n```\nUse your Development keys (not Production) from the Intuit developer dashboard.\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\nCopyright (c) 2026 NyxTools\n",
  "bytes": 8508,
  "sha": "d5364b2e9c7c0d5df49fd8f3c626087bb516b40efc4a53afb1e1dcd01ca369bb",
  "repo_slug": "nyxtoolsdev/quickbooks-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nyxtoolsdev_quickbooks_mcp_ser_73559d1e/readme"
}