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

143 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

Create a .env file in the root directory:

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

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

Go to the Intuit Developer Portal
Create a new app or select an existing one
Get the Client ID and Client Secret from the app's keys section
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 335 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 (335 tests)
│   ├── handlers/    # Handler tests (11 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:

Verify all environment variables are set correctly
Check that tokens are valid and not expired
Ensure the QuickBooks app has the correct redirect URIs
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

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github		.github
docs		docs
src		src
tests		tests
.env		.env
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

QuickBooks Online MCP Server

Overview

Key Features

Quick Start

Installation

Configuration

Claude Code Integration

Available Tools

Entities

Reports

Tool Reference

Authentication

Getting QuickBooks API Credentials

Option 1: Using Environment Variables (Recommended)

Option 2: OAuth Flow

Development

Building

Testing

Project Structure

Documentation

Error Handling

Contributing

License

Acknowledgments

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

QuickBooks Online MCP Server

Overview

Key Features

Quick Start

Installation

Configuration

Claude Code Integration

Available Tools

Entities

Reports

Tool Reference

Authentication

Getting QuickBooks API Credentials

Option 1: Using Environment Variables (Recommended)

Option 2: OAuth Flow

Development

Building

Testing

Project Structure

Documentation

Error Handling

Contributing

License

Acknowledgments

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages