quickbooks-online-mcp-server
The QuickBooks MCP Server lets AI assistants access QuickBooks data via a standard interface. It uses the Model Context Protocol to expose QBO features as callable tools, enabling developers to build AI apps that fetch real-time QBO data through MCP.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/intuit--quickbooks-online-mcp-server)HTML
<a href="/listings/intuit--quickbooks-online-mcp-server"><img src="/api/listings/intuit--quickbooks-online-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Installation
# Clone the repository git clone https://github.com/your-username/mcp-quickbooks-online.git cd mcp-quickbooks-online # Install dependencies npm install # Build the project npm run build
Configuration
Copy the template `.env.example` to `.env` in the root directory and fill in your values:
cp .env.example .env
QUICKBOOKS_CLIENT_ID=your_client_id QUICKBOOKS_CLIENT_SECRET=your_client_secret QUICKBOOKS_ENVIRONMENT=sandbox QUICKBOOKS_REFRESH_TOKEN=your_refresh_token QUICKBOOKS_REALM_ID=your_realm_id # Optional: restrict which tool categories are registered (default: all enabled) # QUICKBOOKS_DISABLE_WRITE=true # suppress create_* tools # QUICKBOOKS_DISABLE_UPDATE=true # suppress update_* tools # QUICKBOOKS_DISABLE_DELETE=true # suppress delete_* tools
`.env` is gitignored so your real credentials stay local.
> **Read-only or containerized installs:** the server reads `.env` at startup and writes the rotated refresh token back to it on each refresh. When the installed module sits on a **read-only filesystem** (a container with a read-only root, an immutable/Nix install), set `QUICKBOOKS_TOKEN_STORE_PATH` to an absolute, writable path for both operations. A per-tenant host can also point each connection at its own isolated token file this way. Three things to know: it must be set in the **host process env** (e.g. the `env` block of your MCP server config) — setting it inside `.env` has no effect, because the path is resolved before `.env` is read; it must be an **absolute** path (the server refuses to start otherwise); and when set, the package's own `.env` is not read at all, so any file-based config (including credentials) must live in the file it points to.
Claude Code Integration
Add to your Claude Code MCP configuration:
{
"mcpServers": {
"quickbooks": {
"command": "node",
"args": ["path/to/mcp-quickbooks-online/dist/index.js"],
"env": {
"QUICKBOOKS_CLIENT_ID": "your_client_id",
"QUICKBOOKS_CLIENT_SECRET": "your_client_secret",
"QUICKBOOKS_REFRESH_TOKEN": "your_refresh_token",
"QUICKBOOKS_REALM_ID": "your_realm_id",
"QUICKBOOKS_ENVIRONMENT": "sandbox",
"QUICKBOOKS_DISABLE_WRITE": "false",
"QUICKBOOKS_DISABLE_UPDATE": "false",
"QUICKBOOKS_DISABLE_DELETE": "false"
}
}
}
}Set any of the `DISABLE_*` flags to `"true"` to prevent that category of tools from being registered. Read tools (`get_*`, `search_*`) are always available.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 504 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # QuickBooks Online MCP Server
- <div align="center">
- **A comprehensive Model Context Protocol (MCP) server for QuickBooks Online**
- [](LICENSE)
- [](#available-tools)
- [](#entities)
- [](#reports)
- [](#testing)
- [](#testing)
- [Quick Start](#quick-start) | [Available Tools](#available-tools) | [Authentication](#authentication) | [Documentation](#documentation)
- </div>
- ---
- ## Overview
- This MCP server provides complete QuickBooks Online API integration for Claude Code and other MCP-compatible clients. It includes full CRUD operations for 29 entity types and 11 financial reports, giving you comprehensive access to QuickBooks Online functionality.
- ### Key Features
- - **145 Total Tools** - Complete coverage of QuickBooks Online API
- - **29 Entity Types** - Full CRUD operations (Create, Read, Update, Delete, Search)
- - **11 Financial Reports** - Balance Sheet, P&L, Cash Flow, and more
- - **OAuth 2.0 Authentication** - Secure token-based authentication
- - **TypeScript** - Full type safety with Zod validation
- - **Tested** - Jest test suite with ESM support
- > Note: this is a local MCP server. It runs as a stdio subprocess on the developer's or partner's machine and authenticates to a QuickBooks Online company.
- > **Before you start:** This MCP server is easy to run once authenticated, but QuickBooks Online integration is gated by Intuit's OAuth app setup. You must register an app on the [Intuit Developer Portal](https://developer.intuit.com) and complete a one-time, browser-based OAuth handshake. **Sandbox** supports `http://localhost` redirect URIs; **production** requires a public HTTPS callback for the initial authorization. After that initial handshake, the server runs locally without further browser interaction (until the 100-day refresh window lapses). See [Authentication](#authentication) for full details.
- ---
- ## Quick Start
- ### Installation
- ```bash
- # Clone the repository
- git clone https://github.com/your-username/mcp-quickbooks-online.git
- cd mcp-quickbooks-online
- # Install dependencies
- npm install
- # Build the project
- npm run build
- ```
- ### Configuration
- Copy the template `.env.example` to `.env` in the root directory and fill in your values:
- ```bash
- cp .env.example .env
- ```
- ```env
- QUICKBOOKS_CLIENT_ID=your_client_id
- QUICKBOOKS_CLIENT_SECRET=your_client_secret
- QUICKBOOKS_ENVIRONMENT=sandbox
- QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
- QUICKBOOKS_REALM_ID=your_realm_id
- # Optional: restrict which tool categories are registered (default: all enabled)
- # QUICKBOOKS_DISABLE_WRITE=true # suppress create_* tools
- # QUICKBOOKS_DISABLE_UPDATE=true # suppress update_* tools
- # QUICKBOOKS_DISABLE_DELETE=true # suppress delete_* tools
- ```
- `.env` is gitignored so your real credentials stay local.
- > **Read-only or containerized installs:** the server reads `.env` at startup and writes the rotated refresh token back to it on each refresh. When the installed module sits on a **read-only filesystem** (a container with a read-only root, an immutable/Nix install), set `QUICKBOOKS_TOKEN_STORE_PATH` to an absolute, writable path for both operations. A per-tenant host can also point each connection at its own isolated token file this way. Three things to know: it must be set in the **host process env** (e.g. the `env` block of your MCP server config) — setting it inside `.env` has no effect, because the path is resolved before `.env` is read; it must be an **absolute** path (the server refuses to start otherwise); and when set, the package's own `.env` is not read at all, so any file-based config (including credentials) must live in the file it points to.
- ### Claude Code Integration
- Add to your Claude Code MCP configuration:
- ```json
- {
- "mcpServers": {
- "quickbooks": {
- "command": "node",
- "args": ["path/to/mcp-quickbooks-online/dist/index.js"],
- "env": {
- "QUICKBOOKS_CLIENT_ID": "your_client_id",
- "QUICKBOOKS_CLIENT_SECRET": "your_client_secret",
- "QUICKBOOKS_REFRESH_TOKEN": "your_refresh_token",
- "QUICKBOOKS_REALM_ID": "your_realm_id",
- "QUICKBOOKS_ENVIRONMENT": "sandbox",
- "QUICKBOOKS_DISABLE_WRITE": "false",
- "QUICKBOOKS_DISABLE_UPDATE": "false",
- "QUICKBOOKS_DISABLE_DELETE": "false"
- }
- }
- }
- }
- ```
- Set any of the `DISABLE_*` flags to `"true"` to prevent that category of tools from being registered. Read tools (`get_*`, `search_*`) are always available.
- ---
- ## Available Tools
- ### Entities
- Complete CRUD operations are available for all entity types:
- | Entity | Create | Get | Update | Delete | Search |
- |--------|:------:|:---:|:------:|:------:|:------:|
- | **Customer** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Invoice** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Estimate** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Bill** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Vendor** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Employee** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Account** | ✅ | ✅ | ✅ | - | ✅ |
- | **Item** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Journal Entry** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Bill Payment** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Purchase** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Payment** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Sales Receipt** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Credit Memo** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Refund Receipt** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Purchase Order** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Vendor Credit** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Deposit** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Transfer** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Time Activity** | ✅ | ✅ | ✅ | ✅ | ✅ |
- | **Class** | ✅ | ✅ | ✅ | - | ✅ |
- | **Department** | ✅ | ✅ | ✅ | - | ✅ |
- | **Term** | ✅ | ✅ | ✅ | - | ✅ |
- | **Payment Method** | ✅ | ✅ | ✅ | - | ✅ |
- | **Tax Code** | - | ✅ | - | - | ✅ |
- | **Tax Rate** | - | ✅ | - | - | ✅ |
- | **Tax Agency** | - | ✅ | - | - | ✅ |
- | **Company Info** | - | ✅ | ✅ | - | - |
- | **Attachable** | ✅ | ✅ | ✅ | ✅ | ✅ |
- ### Reports
- | Report | Tool Name | Description |
- |--------|-----------|-------------|
- | **Balance Sheet** | `get_balance_sheet` | Assets, liabilities, and equity snapshot |
- | **Profit & Loss** | `get_profit_and_loss` | Income and expenses over a period |
- | **Cash Flow** | `get_cash_flow` | Cash inflows and outflows |
- | **Trial Balance** | `get_trial_balance` | Debit and credit balances |
- | **General Ledger** | `get_general_ledger` | Complete transaction history |
- | **Customer Sales** | `get_customer_sales` | Sales by customer |
- | **Aged Receivables** | `get_aged_receivables` | Outstanding customer invoices |
- | **Aged Receivables Detail** | `get_aged_receivables_detail` | Detailed aging breakdown |
- | **Customer Balance** | `get_customer_balance` | Current customer balances |
- | **Aged Payables** | `get_aged_payables` | Outstanding vendor bills |
- | **Vendor Expenses** | `get_vendor_expenses` | Expenses by vendor |
- ---
- ## Tool Reference
- <details>
- <summary><strong>Customer Tools</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `create_customer` | Create a new customer |
- | `get_customer` | Get customer by ID |
- | `update_customer` | Update customer details |
- | `delete_customer` | Delete a customer |
- | `search_customers` | Search customers with filters |
- </details>
- <details>
- <summary><strong>Invoice Tools</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `create_invoice` | Create a new invoice |
- | `get_invoice` | Get invoice by ID |
- | `update_invoice` | Update invoice details |
- | `delete_invoice` | Delete/void an invoice |
- | `search_invoices` | Search invoices with filters |
- | `get_invoice_pdf` | Download an invoice as a PDF (inline base64, or to disk when `QBO_PDF_OUTPUT_DIR` is set) |
- </details>
- <details>
- <summary><strong>Payment Tools</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `create_payment` | Record a customer payment |
- | `get_payment` | Get payment by ID |
- | `update_payment` | Update payment details |
- | `delete_payment` | Void a payment |
- | `search_payments` | Search payments with filters |
- </details>
- <details>
- <summary><strong>Bill & Vendor Tools</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `create_bill` | Create a new bill |
- | `get_bill` | Get bill by ID |
- | `update_bill` | Update bill details |
- | `delete_bill` | Delete a bill |
- | `search_bills` | Search bills with filters |
- | `create_vendor` | Create a new vendor |
- | `get_vendor` | Get vendor by ID |
- | `update_vendor` | Update vendor details |
- | `delete_vendor` | Delete a vendor |
- | `search_vendors` | Search vendors with filters |
- | `create_bill_payment` | Create a bill payment |
- | `get_bill_payment` | Get bill payment by ID |
- | `update_bill_payment` | Update bill payment |
- | `delete_bill_payment` | Delete a bill payment |
- | `search_bill_payments` | Search bill payments |
- </details>
- <details>
- <summary><strong>Sales Receipt & Credit Memo Tools</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `create_sales_receipt` | Create a sales receipt |
- | `get_sales_receipt` | Get sales receipt by ID |
- | `update_sales_receipt` | Update sales receipt |
- | `delete_sales_receipt` | Void a sales receipt |
- | `search_sales_receipts` | Search sales receipts |
- | `create_credit_memo` | Create a credit memo |
- | `get_credit_memo` | Get credit memo by ID |
- | `update_credit_memo` | Update credit memo |
- | `delete_credit_memo` | Void a credit memo |
- | `search_credit_memos` | Search credit memos |
- | `create_refund_receipt` | Create a refund receipt |
- | `get_refund_receipt` | Get refund receipt by ID |
- | `update_refund_receipt` | Update refund receipt |
- | `delete_refund_receipt` | Void a refund receipt |
- | `search_refund_receipts` | Search refund receipts |
- </details>
- <details>
- <summary><strong>Banking Tools</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `create_deposit` | Create a bank deposit |
- | `get_deposit` | Get deposit by ID |
- | `update_deposit` | Update deposit details |
- | `delete_deposit` | Delete a deposit |
- | `search_deposits` | Search deposits |
- | `create_transfer` | Create an account transfer |
- | `get_transfer` | Get transfer by ID |
- | `update_transfer` | Update transfer details |
- | `delete_transfer` | Delete a transfer |
- | `search_transfers` | Search transfers |
- </details>
- <details>
- <summary><strong>Purchase Order & Vendor Credit Tools</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `create_purchase_order` | Create a purchase order |
- | `get_purchase_order` | Get purchase order by ID |
- | `update_purchase_order` | Update purchase order |
- | `delete_purchase_order` | Delete a purchase order |
- | `search_purchase_orders` | Search purchase orders |
- | `create_vendor_credit` | Create a vendor credit |
- | `get_vendor_credit` | Get vendor credit by ID |
- | `update_vendor_credit` | Update vendor credit |
- | `delete_vendor_credit` | Delete a vendor credit |
- | `search_vendor_credits` | Search vendor credits |
- </details>
- <details>
- <summary><strong>Time Tracking Tools</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `create_time_activity` | Create a time activity |
- | `get_time_activity` | Get time activity by ID |
- | `update_time_activity` | Update time activity |
- | `delete_time_activity` | Delete a time activity |
- | `search_time_activities` | Search time activities |
- </details>
- <details>
- <summary><strong>Classification Tools</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `create_class` | Create a class |
- | `get_class` | Get class by ID |
- | `update_class` | Update class details |
- | `search_classes` | Search classes |
- | `create_department` | Create a department |
- | `get_department` | Get department by ID |
- | `update_department` | Update department |
- | `search_departments` | Search departments |
- </details>
- <details>
- <summary><strong>Settings Tools</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `create_term` | Create a payment term |
- | `get_term` | Get term by ID |
- | `update_term` | Update term details |
- | `search_terms` | Search terms |
- | `create_payment_method` | Create a payment method |
- | `get_payment_method` | Get payment method by ID |
- | `update_payment_method` | Update payment method |
- | `search_payment_methods` | Search payment methods |
- | `get_preferences` | Get company accounting and feature preferences |
- </details>
- <details>
- <summary><strong>Tax Tools</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `get_tax_code` | Get tax code by ID |
- | `search_tax_codes` | Search tax codes |
- | `get_tax_rate` | Get tax rate by ID |
- | `search_tax_rates` | Search tax rates |
- | `get_tax_agency` | Get tax agency by ID |
- | `search_tax_agencies` | Search tax agencies |
- </details>
- <details>
- <summary><strong>Company & Attachments</strong></summary>
- | Tool | Description |
- |------|-------------|
- | `get_company_info` | Get company information |
- | `update_company_info` | Update company info |
- | `create_attachable` | Create an attachment |
- | `get_attachable` | Get attachment by ID |
- | `update_attachable` | Update attachment |
- | `delete_attachable` | Delete an attachment |
- | `search_attachables` | Search attachments |
- </details>
- ---
- ## Authentication
- This server uses OAuth 2.0 to authenticate to a QuickBooks Online company. You'll set up an app on the [Intuit Developer Portal](https://developer.intuit.com/) and connect it to either a **sandbox** (for development) or your **production** QBO company.
- ### Important: Sandbox vs Production
- | Mode | When to use | Redirect URI accepted | Setup difficulty |
- |------|-------------|------------------------|------------------|
- | **Sandbox** | Development, testing, demos | `http://localhost:8000/callback` works | Easy |
- | **Production** | Real company data | Localhost **rejected** — must be a public HTTPS URL | Harder (see below) |
- If you only want to read your own company's data, you still need to set up an app — Intuit does not offer per-user API keys. There is no shortcut around the OAuth + app-creation flow.
- ### Sandbox Setup (recommended for first run)
- 1. Go to the [Intuit Developer Portal](https://developer.intuit.com/) and create a new app
- 2. Open the app → **Settings** (left sidebar) → **Redirect URIs** → add: `http://localhost:8000/callback`
- 3. Get your **Client ID** and **Client Secret** from the app's **Keys & Credentials** page (Development keys)
- 4. Create or use a sandbox company under the **Sandbox** top-level menu item in the dev portal
- 5. Set `QUICKBOOKS_ENVIRONMENT=sandbox` in your `.env`
- 6. Run `npm run auth` to complete the OAuth handshake — your browser will open, you sign in to the sandbox company, tokens are saved to `.env`
- ### Production Setup
- The Intuit Developer Portal **rejects `http://localhost` redirect URIs in production mode** — every contributor hits this. Two known workarounds:
- 1. **ngrok tunnel (most common):** run `ngrok http 8000`, then on your Intuit app go to **Settings → Redirect URIs** and add the generated `https://<id>.ngrok-free.app/callback` URL. Use that URL for the OAuth handshake, then revert to localhost afterwards.
- 2. **Deploy a small public callback handler** (e.g., on a VPS or serverless function) that captures the auth code and hands it back to your local setup. More involved; only needed if you can't use ngrok.
- After completing the production OAuth handshake, the refresh token is what matters — once it's in `.env`, you no longer need the public redirect URL for day-to-day use. Refresh tokens auto-rotate; the server persists the new token on each refresh.
- ### Once you have tokens
- ```env
- QUICKBOOKS_CLIENT_ID=your_client_id
- QUICKBOOKS_CLIENT_SECRET=your_client_secret
- QUICKBOOKS_REFRESH_TOKEN=your_refresh_token
- QUICKBOOKS_REALM_ID=your_realm_id
- QUICKBOOKS_ENVIRONMENT=sandbox # or 'production'
- ```
- ### Common pitfalls
- - **`.env` loaded from the wrong directory.** The server resolves `.env` relative to the compiled module, not your shell's CWD. If you launch via Claude Desktop, this matters — make sure you're on current `main`.
- - **Redirect URI mismatch.** The URI you register in the Intuit portal must match **exactly** — protocol, host, port, path. `http://localhost:8000/callback` .
- ---
- ## Development
- ### Building
- ```bash
- npm run build
- ```
- ### Testing
- ```bash
- npm test
- ```
- The test suite includes **396 tests** with **100% code coverage** across all metrics (statements, branches, functions, lines).
- ### Project Structure
- ```
- src/
- ├── clients/ # QuickBooks API client
- ├── handlers/ # Business logic handlers (87 files)
- ├── tools/ # MCP tool definitions
- ├── helpers/ # Utility functions
- ├── types/ # TypeScript types
- └── index.ts # Server entry point
- tests/
- ├── unit/ # Unit tests (396 tests)
- │ ├── handlers/ # Handler tests (15 test files)
- │ └── helpers/ # Helper tests
- └── mocks/ # Test mocks
- docs/
- ├── ARCHITECTURE.md # System architecture & design patterns
- ├── TESTING.md # Testing guide & patterns
- └── plans/ # Development plans
- ```
- ---
- ## Documentation
- | Document | Description |
- |----------|-------------|
- | [CHANGELOG.md](CHANGELOG.md) | Version history and all changes |
- | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture, patterns, and design decisions |
- | [docs/TESTING.md](docs/TESTING.md) | Testing strategy, ESM patterns, and coverage guide |
- ---
- ## Error Handling
- If you encounter connection errors:
- 1. Verify all environment variables are set correctly
- 2. Check that tokens are valid and not expired
- 3. Ensure the QuickBooks app has the correct redirect URIs
- 4. For sandbox testing, use `QUICKBOOKS_ENVIRONMENT=sandbox`
- ---
- ## Contributing
- Contributions are welcome! Please feel free to submit a Pull Request.
- ### Tool naming convention
- All tool names must follow the `{verb}_{entity}` convention using underscores. The verb prefix determines CRUD Restriction Mode behaviour:
- | Prefix | Category | Suppressed by |
- |--------|----------|---------------|
- | `create_` | WRITE | `QUICKBOOKS_DISABLE_WRITE=true` |
- | `update_` | UPDATE | `QUICKBOOKS_DISABLE_UPDATE=true` |
- | `delete_` | DELETE | `QUICKBOOKS_DISABLE_DELETE=true` |
- | `get_`, `search_`, `read_` | READ | never |
- New tools that do not follow this convention will not be correctly categorised and may appear or be suppressed unexpectedly.
- ---
- ## License
- MIT License - see [LICENSE](LICENSE) for details.
- ---
- ## Acknowledgments
- - Based on [Intuit's QuickBooks Online MCP Server](https://github.com/intuit/quickbooks-online-mcp-server)
- - Built with the [Model Context Protocol](https://modelcontextprotocol.io/)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.