qb-mcp — QuickBooks Online MCP Server

A premium Model Context Protocol (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 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 (or use the Postman collection).
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

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

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

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

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

{
  "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

# 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