175 lines
4.5 KiB
Markdown
175 lines
4.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create a `.env` file (see `.env.example`):
|
|
|
|
```bash
|
|
# 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](https://developer.intuit.com)
|
|
2. Configure OAuth2 redirect URIs
|
|
3. Obtain access token and realm ID via OAuth flow
|
|
4. Store refresh token for automatic renewal
|
|
|
|
## Usage
|
|
|
|
### Development
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### Production
|
|
|
|
```bash
|
|
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
|
|
|
|
```typescript
|
|
const result = await client.query(
|
|
'SELECT * FROM Invoice WHERE TotalAmt > 1000',
|
|
{ startPosition: 1, maxResults: 100 }
|
|
);
|
|
```
|
|
|
|
### Create Customer
|
|
|
|
```typescript
|
|
const customer = await client.create('Customer', {
|
|
DisplayName: 'Acme Corp',
|
|
PrimaryEmailAddr: { Address: 'billing@acme.com' },
|
|
});
|
|
```
|
|
|
|
### Update Invoice (with SyncToken)
|
|
|
|
```typescript
|
|
const invoice = await client.update('Invoice', {
|
|
Id: '123',
|
|
SyncToken: '0',
|
|
TotalAmt: 5000,
|
|
});
|
|
```
|
|
|
|
### Get Reports
|
|
|
|
```typescript
|
|
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](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/invoice)
|
|
- [Query Language](https://developer.intuit.com/app/developer/qbo/docs/develop/explore-the-quickbooks-online-api/data-queries)
|
|
- [OAuth Guide](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization)
|
|
|
|
## 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.
|