mcpengine/servers/quickbooks

QuickBooks Online MCP Server

Model Context Protocol (MCP) server for QuickBooks Online integration.

Features

• Full QBO API Coverage: Invoices, Customers, Vendors, Bills, Payments, Estimates, Items, Accounts, Reports, and more
• SQL-like Queries: Native support for QBO's query language
• Rate Limiting: Respects QBO's 500 req/min throttle with automatic retry
• Optimistic Locking: SyncToken support for safe updates
• Sandbox Support: Test against QBO Sandbox environment
• Type Safety: Comprehensive TypeScript types for all QBO entities
• Pagination: Automatic handling of large result sets
• Token Refresh: Built-in OAuth2 token refresh support

Installation

npm install

Configuration

Create a .env file (see .env.example):

# Required
QBO_ACCESS_TOKEN=your_access_token
QBO_REALM_ID=your_realm_id

# Optional
QBO_REFRESH_TOKEN=your_refresh_token
QBO_SANDBOX=false
QBO_MINOR_VERSION=73

Getting OAuth Credentials

1. Create an app at Intuit Developer Portal
2. Configure OAuth2 redirect URIs
3. Obtain access token and realm ID via OAuth flow
4. Store refresh token for automatic renewal

Usage

Development

npm run dev

Production

npm run build
npm start

Architecture

Foundation Components

• src/types/index.ts: Comprehensive TypeScript interfaces for all QBO entities
• src/clients/quickbooks.ts: Full-featured QBO API client with retry, rate limiting, and pagination
• src/server.ts: MCP server with lazy-loaded tool modules
• src/main.ts: Entry point with environment validation and dual transport

QuickBooks Client Features

• OAuth2 Bearer authentication
• Automatic retry with exponential backoff (3 retries)
• Rate limit handling (500 req/min)
• Pagination support (startPosition + maxResults)
• SQL-like query execution
• Batch operations (up to 30 per batch)
• Token refresh helper
• Sandbox/production environment switching

Tool Categories (Lazy-Loaded)

Tool implementations will be added in:

• src/tools/invoices.ts - Create, read, update, send invoices
• src/tools/customers.ts - Customer management
• src/tools/payments.ts - Payment processing
• src/tools/estimates.ts - Estimate creation and conversion
• src/tools/bills.ts - Bill management
• src/tools/vendors.ts - Vendor operations
• src/tools/items.ts - Inventory and service items
• src/tools/accounts.ts - Chart of accounts
• src/tools/reports.ts - P&L, Balance Sheet, Cash Flow, etc.
• src/tools/employees.ts - Employee management
• src/tools/time-activities.ts - Time tracking
• src/tools/taxes.ts - Tax codes and rates
• src/tools/purchases.ts - Purchase orders and expenses
• src/tools/journal-entries.ts - Manual journal entries

API Examples

Query Invoices

const result = await client.query(
  'SELECT * FROM Invoice WHERE TotalAmt > 1000',
  { startPosition: 1, maxResults: 100 }
);

Create Customer

const customer = await client.create('Customer', {
  DisplayName: 'Acme Corp',
  PrimaryEmailAddr: { Address: 'billing@acme.com' },
});

Update Invoice (with SyncToken)

const invoice = await client.update('Invoice', {
  Id: '123',
  SyncToken: '0',
  TotalAmt: 5000,
});

Get Reports

const profitLoss = await client.getReport('ProfitAndLoss', {
  start_date: '2024-01-01',
  end_date: '2024-12-31',
  accounting_method: 'Accrual',
});

QuickBooks Online API Reference

• API Documentation
• Query Language
• OAuth Guide

Type Safety

All QBO entities use:

• Branded types for IDs (prevents mixing Customer/Vendor/etc. IDs)
• Discriminated unions for entity types and statuses
• SyncToken for optimistic locking on all entities
• Strict TypeScript mode for compile-time safety

Rate Limiting

QBO enforces 500 requests/minute:

• Client tracks requests per rolling window
• Automatically throttles when approaching limit
• Retries 429 responses with exponential backoff

Error Handling

QBO errors include:

• Error code
• Message
• Detail
• Element (field causing error)

The client wraps these in structured MCP errors.

License

MIT

Contributing

This is the foundation layer. Tool implementations and UI apps will be added separately.