QuickBooks Online MCP Server

A comprehensive Model Context Protocol (MCP) server for QuickBooks Online

Quick Start | Available Tools | Authentication | Documentation

---

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

• 144 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

---

Quick Start

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

.env is gitignored so your real credentials stay local.

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"
      }
    }
  }
}

---

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

| 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 |

| 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 |

| 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 |

| 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 |

| 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 |

| 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 |

| 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 |

| 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 |

| 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 |

| 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 |

| 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 |

| 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 |

---

Authentication

Getting QuickBooks API Credentials

1. Go to the Intuit Developer Portal
2. Create a new app or select an existing one
3. Get the Client ID and Client Secret from the app's keys section
4. Add http://localhost:8000/callback to the app's Redirect URIs

Option 1: Using Environment Variables (Recommended)

If you have existing tokens:

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

Option 2: OAuth Flow

If you don't have tokens, the server can initiate an OAuth flow that:

• Starts a temporary local server
• Opens your browser for authentication
• Saves tokens to your .env file
• Closes automatically when complete

---

Development

Building

npm run build

Testing

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 | Version history and all changes | | docs/ARCHITECTURE.md | System architecture, patterns, and design decisions | | 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.

---

License

MIT License - see LICENSE for details.

---

Acknowledgments

• Based on Intuit's QuickBooks Online MCP Server
• Built with the Model Context Protocol