# qb-mcp — QuickBooks Online MCP Server

A premium [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets AI agents (Claude, Cursor, Cline, etc.) interact with your QuickBooks Online account.

## Features

**20 tools** covering the full QuickBooks Online workflow:

| Category | Tools |
|----------|-------|
| **Invoices** | `list_invoices`, `create_invoice`, `get_invoice`, `send_invoice` |
| **Customers** | `list_customers`, `create_customer`, `get_customer` |
| **Payments** | `record_payment`, `list_payments` |
| **Accounts** | `list_accounts` |
| **Reports** | `get_profit_loss`, `get_balance_sheet` |
| **Expenses** | `create_expense`, `list_expenses` |
| **Items** | `list_items`, `create_item` |
| **Vendors** | `list_vendors`, `create_vendor` |
| **Bills** | `create_bill`, `list_bills` |

## Prerequisites

- **Node.js** 18 or later
- A **QuickBooks Online** account (sandbox or production)
- An **Intuit Developer** account with an OAuth 2.0 app

## Setup

### 1. Create an Intuit Developer App

1. Go to [developer.intuit.com](https://developer.intuit.com) and sign in (or create an account).
2. Navigate to **Dashboard → Create an app**.
3. Select **QuickBooks Online and Payments** as the platform.
4. Give your app a name (e.g., "MCP Server").
5. Under **Keys & credentials**, note your **Client ID** and **Client Secret**.
6. Add `http://localhost:3000/callback` as a **Redirect URI**.
7. Under **Scopes**, ensure `com.intuit.quickbooks.accounting` is selected.

### 2. Get Your Sandbox Company ID

1. In the Intuit Developer dashboard, go to **Sandbox** in the left sidebar.
2. You'll see a sandbox company — note the **Company ID** (also called Realm ID).
3. You can also find this in the URL when logged into QuickBooks Online: `https://app.qbo.intuit.com/app/homepage?companyId=XXXXXXXXX`.

### 3. Get OAuth Tokens

For initial setup, you'll need to complete the OAuth 2.0 authorization flow to get your access and refresh tokens:

1. Visit the [Intuit OAuth Playground](https://developer.intuit.com/app/developer/playground) (or use the [Postman collection](https://developer.intuit.com/app/developer/qbo/docs/develop/postman)).
2. Select your app and the `com.intuit.quickbooks.accounting` scope.
3. Authorize and connect to your sandbox company.
4. Copy the **Access Token** and **Refresh Token**.

> **Note:** Access tokens expire after 1 hour. The MCP server automatically refreshes them using the refresh token (valid for 100 days). After initial setup, tokens are stored in `~/.qb-mcp/tokens.json`.

### 4. Install and Configure

```bash
# Clone and install
git clone <repo-url> qb-mcp
cd qb-mcp
npm install

# Configure environment
cp config/.env.example .env
```

Edit `.env` with your credentials:

```env
QB_CLIENT_ID=your_client_id
QB_CLIENT_SECRET=your_client_secret
QB_REDIRECT_URI=http://localhost:3000/callback
QB_REALM_ID=your_company_id
QB_ENVIRONMENT=sandbox
QB_ACCESS_TOKEN=your_access_token
QB_REFRESH_TOKEN=your_refresh_token
```

### 5. Build

```bash
npm run build
```

### 6. Connect to Claude Desktop

Add this to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["/absolute/path/to/qb-mcp/dist/index.js"],
      "env": {
        "QB_CLIENT_ID": "your_client_id",
        "QB_CLIENT_SECRET": "your_client_secret",
        "QB_REALM_ID": "your_company_id",
        "QB_ENVIRONMENT": "sandbox",
        "QB_ACCESS_TOKEN": "your_access_token",
        "QB_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}
```

Alternatively, if you have a `.env` file in the project root, you can use:

```json
{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["/absolute/path/to/qb-mcp/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop after updating the config. You should see the QuickBooks tools available in the tools menu.

## Usage Examples

Once connected, you can ask your AI agent things like:

- "List all unpaid invoices"
- "Create an invoice for customer #42 with 2 hours of consulting at $150/hr"
- "Show me the profit and loss report for last quarter"
- "Record a $500 payment from customer #42 against invoice #1001"
- "List all vendors"
- "Create a bill from vendor #5 for $200 in office supplies"

## Development

```bash
# Run in development mode (with tsx for hot-reload)
npm run dev

# Run tests
npm test

# Watch tests
npm run test:watch

# Type-check without building
npm run lint

# Build for production
npm run build
```

## Switching to Production

1. In your `.env`, change `QB_ENVIRONMENT=production`.
2. Complete the OAuth flow against your real QuickBooks company (not sandbox).
3. Update `QB_REALM_ID` to your production company ID.
4. Update your access and refresh tokens.

> **Important:** Always test thoroughly in sandbox before connecting to production data.

## License

MIT