qbo-mcp

qbo-mcp

A Model Context Protocol (MCP) server for the QuickBooks Online Accounting API. Manage customers, vendors, invoices, bills, payments, items, reports, and more — all from Claude.

Supports both stdio (Claude Desktop) and HTTP/SSE (Railway / remote clients).

---

Tools (48 total)

| Category | Tool | Description | |---|---|---| | Accounts | list_accounts | Query chart of accounts with optional WHERE filter | | | get_account | Get account by ID | | | create_account | Create a new account | | | update_account | Sparse-update an account | | Customers | list_customers | Query customers | | | get_customer | Get customer by ID | | | create_customer | Create a new customer | | | update_customer | Sparse-update a customer | | Vendors | list_vendors | Query vendors | | | get_vendor | Get vendor by ID | | | create_vendor | Create a new vendor | | | update_vendor | Sparse-update a vendor | | Items | list_items | Query products/services | | | get_item | Get item by ID | | | create_item | Create a new item | | | update_item | Sparse-update an item | | Invoices | list_invoices | Query invoices | | | get_invoice | Get invoice by ID | | | create_invoice | Create a new invoice | | | update_invoice | Sparse-update an invoice | | | delete_invoice | Delete/void an invoice | | Bills | list_bills | Query vendor bills | | | get_bill | Get bill by ID | | | create_bill | Create a new bill | | | update_bill | Sparse-update a bill | | | delete_bill | Delete a bill | | Payments | list_payments | Query customer payments | | | get_payment | Get payment by ID | | | create_payment | Record a customer payment | | | delete_payment | Delete a payment | | Purchases | list_purchases | Query purchases/expenses | | | get_purchase | Get purchase by ID | | | create_purchase | Create a purchase/expense | | | delete_purchase | Delete a purchase | | Estimates | list_estimates | Query estimates/quotes | | | get_estimate | Get estimate by ID | | | create_estimate | Create a new estimate | | | delete_estimate | Delete an estimate | | Sales Receipts | list_sales_receipts | Query sales receipts | | | get_sales_receipt | Get sales receipt by ID | | | create_sales_receipt | Create a new sales receipt | | | delete_sales_receipt | Delete a sales receipt | | Credit Memos | list_credit_memos | Query credit memos | | | get_credit_memo | Get credit memo by ID | | | create_credit_memo | Create a new credit memo | | Transfers | list_transfers | Query account transfers | | | get_transfer | Get transfer by ID | | | create_transfer | Create a funds transfer | | Company | get_company_info | Get company details | | Reports | get_profit_and_loss_report | P&L / Income Statement | | | get_balance_sheet_report | Balance Sheet | | | get_cash_flow_report | Cash Flow Statement | | | get_accounts_receivable_aging_report | A/R Aging Summary | | | get_accounts_payable_aging_report | A/P Aging Summary | | | get_trial_balance_report | Trial Balance | | Query | query_qbo | Run a custom SQL-style QBO query |

---

Environment Variables

| Variable | Required | Description | |---|---|---| | QBO_REALM_ID | Yes | Company/Realm ID from your QBO URL | | QBO_CLIENT_ID | For refresh | OAuth 2.0 Client ID from Intuit Developer Portal | | QBO_CLIENT_SECRET | For refresh | OAuth 2.0 Client Secret | | QBO_ACCESS_TOKEN | Yes | OAuth 2.0 access token (expires every 60 min) | | QBO_REFRESH_TOKEN | Yes | OAuth 2.0 refresh token (used for auto-renewal) | | QBO_ENVIRONMENT | No | sandbox (default) or production | | TRANSPORT | No | http (default) or stdio | | PORT | No | HTTP port (default 3000) |

*Either QBO_ACCESS_TOKEN or QBO_REFRESH_TOKEN is required. For production, provide the refresh token plus client credentials for automatic token renewal.

Getting credentials

1. Go to developer.intuit.com and create an app
2. Under Keys & credentials, copy your Client ID and Client Secret
3. Use the OAuth 2.0 Playground in the dev portal to generate an Access Token and Refresh Token
4. Your Realm ID is in the QBO URL: qbo.intuit.com/app/homepage?...realmId=XXXXXXXXXX

---

Claude Desktop Configuration

Remote (Railway)

{
  "mcpServers": {
    "quickbooks": {
      "url": "https://your-app.up.railway.app/sse"
    }
  }
}

Local (stdio)

{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["/absolute/path/to/qbo-mcp/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "QBO_REALM_ID": "your-realm-id",
        "QBO_ACCESS_TOKEN": "your-access-token",
        "QBO_REFRESH_TOKEN": "your-refresh-token",
        "QBO_CLIENT_ID": "your-client-id",
        "QBO_CLIENT_SECRET": "your-client-secret",
        "QBO_ENVIRONMENT": "sandbox"
      }
    }
  }
}

---

Deploy to Railway

Option A — GitHub deployer (recommended)

1. Push this repo to GitHub
2. In Railway: New Project → Deploy from GitHub repo → select this repo
3. Railway auto-detects the Dockerfile and railway.toml
4. Go to Variables and set:

• QBO_REALM_ID
• QBO_ACCESS_TOKEN
• QBO_REFRESH_TOKEN
• QBO_CLIENT_ID
• QBO_CLIENT_SECRET
• QBO_ENVIRONMENT → production (when ready)

1. Go to Settings → Networking → Generate Domain
2. Connect Claude to https://your-app.up.railway.app/sse

Option B — Railway CLI

railway login
railway init
railway up
railway domain

---

Local Development

npm install
cp .env.example .env   # fill in your credentials
npm run build
node dist/index.js