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)
5. Go to Settings → Networking → Generate Domain
6. 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