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

Create an app at Intuit Developer Portal
Configure OAuth2 redirect URIs
Obtain access token and realm ID via OAuth flow
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

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.