QuickBooks Online MCP Server

---

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

Customer Tools

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

Invoice Tools

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

Payment Tools

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

Bill & Vendor Tools

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

Sales Receipt & Credit Memo Tools

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

Banking Tools

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

Purchase Order & Vendor Credit Tools

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

Time Tracking Tools

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

Classification Tools

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

Settings Tools

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

Tax Tools

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

Company & Attachments

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