<div align="center">

QuickBooks Online MCP Server

A local Model Context Protocol (MCP) server that exposes QuickBooks Online data and actions as callable tools for MCP-compatible AI assistants.

</div>

📌 Overview

QuickBooks Online MCP Server provides a standard MCP interface for working with QuickBooks Online data. It runs locally as a stdio subprocess and authenticates to a QuickBooks Online company through Intuit OAuth 2.0.

The server is designed for AI-assisted workflows where an MCP-compatible client needs to read or manage QuickBooks Online entities, search accounting records, or retrieve financial reports through structured tools.

✨ Features

• MCP server for QuickBooks Online
• OAuth 2.0 authentication with Intuit
• Support for sandbox and production QuickBooks Online environments
• Tools for QuickBooks entities such as customers, invoices, bills, vendors, payments, accounts, items, and more
• Financial report tools including Balance Sheet, Profit and Loss, Cash Flow, Trial Balance, and General Ledger
• Optional environment flags to disable write, update, or delete tool categories
• TypeScript implementation with Zod validation
• Jest test suite referenced by the upstream documentation

🧰 Tool Coverage

The server exposes QuickBooks Online functionality through MCP tools.

Entities

Supported entity categories include:

• 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

Most entities support create, get, update, delete, and search operations where QuickBooks Online supports those actions. Some entities are read-only or do not support deletion.

Reports

Available report tools include:

Report	Tool
Balance Sheet	get_balance_sheet
Profit and Loss	get_profit_and_loss
Cash Flow	get_cash_flow
Trial Balance	get_trial_balance
General Ledger	get_general_ledger
Customer Sales	get_customer_sales
Aged Receivables	get_aged_receivables
Aged Receivables Detail	get_aged_receivables_detail
Customer Balance	get_customer_balance
Aged Payables	get_aged_payables
Vendor Expenses	get_vendor_expenses

🔐 Authentication

This server uses Intuit OAuth 2.0. To connect it to QuickBooks Online, you need an app in the Intuit Developer Portal and a completed OAuth authorization flow.

Required environment values include:

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 flags can restrict registered tool categories:

QUICKBOOKS_DISABLE_WRITE=true
QUICKBOOKS_DISABLE_UPDATE=true
QUICKBOOKS_DISABLE_DELETE=true

Read tools such as get_* and search_* remain available.

Sandbox and production notes

• Sandbox usage can use a local callback such as http://localhost:8000/callback.
• Production OAuth setup requires a public HTTPS redirect URI for the initial authorization.
• After the initial OAuth handshake, the server runs locally using the stored refresh token until reauthorization is required.

⚙️ Basic Setup

git clone https://github.com/your-username/mcp-quickbooks-online.git
cd mcp-quickbooks-online
npm install
npm run build

Create a .env file from the provided environment template and fill in the QuickBooks Online OAuth values.

cp .env.example .env

To run the OAuth helper described by the upstream documentation:

npm run auth

🤖 MCP Client Configuration

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

🧪 Development

Build the project:

npm run build

Run tests:

npm test

The upstream README references a Jest test suite and TypeScript implementation.

🧭 Tool Naming

Tool names follow a {verb}_{entity} convention.

Prefix	Category	Restriction flag
create_	Write	QUICKBOOKS_DISABLE_WRITE=true
update_	Update	QUICKBOOKS_DISABLE_UPDATE=true
delete_	Delete	QUICKBOOKS_DISABLE_DELETE=true
get_, search_, read_	Read	Always available

❓ FAQ

What is this project used for?

It provides an MCP interface for QuickBooks Online so AI assistants and other MCP-compatible clients can call QuickBooks-related tools in a structured way.

Does it run as a hosted service?

No. The documented behavior is for a local MCP server that runs as a stdio subprocess on the user’s machine.

Is OAuth required?

Yes. QuickBooks Online access requires Intuit OAuth 2.0 through an app created in the Intuit Developer Portal.

Can write operations be disabled?

Yes. Environment flags can suppress create, update, and delete tools while leaving read tools available.

Does it support reports?

Yes. The documented report tools include Balance Sheet, Profit and Loss, Cash Flow, Trial Balance, General Ledger, customer reports, receivables reports, payables reports, and vendor expenses.

📄 License

MIT License. See LICENSE for details.

🙏 Acknowledgments

This project is based on Intuit’s QuickBooks Online MCP Server and uses the Model Context Protocol.