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

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

Optional flags can restrict registered tool categories:

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

```bash
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.

```bash
cp .env.example .env
```

To run the OAuth helper described by the upstream documentation:

```bash
npm run auth
```

## 🤖 MCP Client Configuration

Example MCP configuration:

```json
{
  "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:

```bash
npm run build
```

Run tests:

```bash
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.