QuickBooks Online MCP Server

This is a Model Context Protocol (MCP) server implementation for QuickBooks Online integration.

Setup

1. Install dependencies:

npm install

2. Create a .env file in the root directory with the following variables:

QUICKBOOKS_CLIENT_ID=your_client_id
QUICKBOOKS_CLIENT_SECRET=your_client_secret
QUICKBOOKS_ENVIRONMENT=sandbox

3. Get your Client ID and Client Secret:

   • 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

Related MCP server: QuickBooks Online MCP Server

Authentication

.env holds only the static app credentials (QUICKBOOKS_CLIENT_ID, QUICKBOOKS_CLIENT_SECRET, QUICKBOOKS_ENVIRONMENT) and is gitignored — copy .env.example to .env to get started. The rotating refresh token and realm ID are persisted separately to .qbo-tokens.json (also gitignored) and managed automatically. The short-lived access token is kept in memory only and re-minted on each launch.

One-time authorization (recommended)

Run the OAuth flow once to connect your QuickBooks company:

npm run auth

This will:

• Start a temporary local server on http://localhost:8000/callback

• Open your default browser automatically

• Redirect you to QuickBooks for authentication

• Save the tokens to .qbo-tokens.json once authenticated

• Close automatically when complete

After that, the server keeps itself authenticated automatically: it refreshes the access token ahead of expiry and persists the rotating refresh token on every refresh. You only need to re-run npm run auth if the refresh token is left unused long enough to expire (100 days idle).

Automatic re-authorization

If the refresh token is ever rejected during a tool call, the server launches the browser flow again automatically. Set QBO_AUTO_REAUTH=false in .env to disable this and instead fail fast with a message telling you to run npm run auth (useful for headless/unattended setups).

Migrating from an older setup

If you already have QUICKBOOKS_REFRESH_TOKEN / QUICKBOOKS_REALM_ID in your .env, they are picked up once on first run and migrated into .qbo-tokens.json. You can delete them from .env afterward.

Usage

After authentication is set up, you can use the MCP server to interact with QuickBooks Online. The server provides various tools for managing customers, estimates, bills, and more.

Available Tools

Added tools for Create, Delete, Get, Search, Update for the following entities:

• Account

• Bill Payment

• Bill

• Customer

• Employee

• Estimate

• Invoice

• Item

• Journal Entry

• Purchase

• Vendor

Report Tools (29 reports)

Run QuickBooks financial reports via report_* tools. All accept optional date range/filter parameters.

Financial Statements:

• report_balance_sheet - Balance Sheet

• report_profit_and_loss - Profit and Loss (Income Statement)

• report_profit_and_loss_detail - Profit and Loss with transaction detail

• report_trial_balance - Trial Balance

• report_cash_flow - Statement of Cash Flows

Sales & Income:

• report_customer_sales - Sales by Customer

• report_item_sales - Sales by Product/Service

• report_customer_income - Income by Customer

• report_department_sales - Sales by Department

• report_class_sales - Sales by Class

Customer Reports:

• report_customer_balance - Customer Balance Summary

• report_customer_balance_detail - Customer Balance Detail

• report_aged_receivables - A/R Aging Summary

• report_aged_receivable_detail - A/R Aging Detail

Vendor Reports:

• report_vendor_balance - Vendor Balance Summary

• report_vendor_balance_detail - Vendor Balance Detail

• report_aged_payables - A/P Aging Summary

• report_aged_payable_detail - A/P Aging Detail

• report_vendor_expenses - Expenses by Vendor

Transaction & Ledger Reports:

• report_transaction_list - Transaction List

• report_transaction_list_with_splits - Transaction List with Splits

• report_transaction_list_by_customer - Transaction List by Customer

• report_transaction_list_by_vendor - Transaction List by Vendor

• report_general_ledger - General Ledger Detail

• report_journal - Journal Report

Other:

• report_inventory_valuation_summary - Inventory Valuation Summary

• report_account_list - Account List Detail

• report_trial_balance_fr - Trial Balance (France only)

• report_tax_summary - Tax Summary (France only)

Error Handling

If you see an error message like "QuickBooks not connected", make sure to:

1. Check that your .env file contains all required variables

2. Verify that your tokens are valid and not expired