Connect your AI Agents to QuickBooks Online in minutes
Available tools
query_accounts
Query Chart of Accounts using SQL-like syntax with filters for account type and active status. Parameters: query (SQL filter), max_results (1-1000), start_position, account_type, active_only. Supports pagination.
get_account
Retrieve comprehensive account details by ID including name, type, sub-type, classification, current balance, parent account, and account number.
create_account
Create Chart of Accounts entry. Specify name, account type (Bank, Other Current Asset, Fixed Asset, etc.), account sub-type, and optional description, account number, or parent account for hierarchy.
update_account
Update account with new name, description, account number, or active status. Uses optimistic locking with sync_token. Cannot change account type.
query_bills
Query bills using SQL-like syntax with filters for vendor, date range, and payment status. Parameters: query (SQL filter), max_results (1-1000), start_position, vendor_id, status (Payable/Paid), start_date, end_date. Supports pagination.
get_bill
Retrieve comprehensive bill details by ID including vendor info, line items with account/item details, amounts, due date, and balance information.
create_bill
Create bill record for vendor with line items for expenses or items. Specify vendor, transaction date, line items with account or item details, and optional due date.
update_bill
Update bill with new vendor, line items, dates, or amounts. Uses optimistic locking with sync_token.
delete_bill
Delete bill by ID permanently. Uses optimistic locking with sync_token.
query_customers
Query customers using SQL-like syntax with filters for name, status, and balance. Parameters: query (SQL filter), max_results, start_position, active_only. Supports pagination.
get_customer
Retrieve comprehensive customer details by ID including contact info, billing and shipping addresses, payment terms, balance info, tax settings, and metadata. Parameters: customer_id (required string). Essential for customer management, invoice creation, and reporting. Requires OAuth 2.0 with accounting scope.
create_customer
Create customer with contact info, addresses, and settings. Parameters: name (required), company_name, display_name, email, phone, bill_addr, ship_addr, taxable, open_balance, open_balance_date, credit_limit. DisplayName must be unique.
update_customer
Update customer with new contact info, addresses, and settings. Uses optimistic locking with sync_token. Parameters: id (required), sync_token (required), name, company_name, email, phone, addresses, taxable, active, credit_limit.
delete_customer
Soft delete customer by setting status to inactive. Preserves historical data and transaction references. Parameters: customer_id (required), sync_token (required). Cannot delete customers with outstanding balances.
check_auth_config
Diagnostic tool to check QuickBooks authentication configuration.
query_estimates
Query estimates using SQL-like syntax with filters for customer, date range, and status. Parameters: query (SQL filter), max_results (1-1000), start_position, customer_id, status (Accepted/Closed/Pending/Rejected), start_date, end_date. Supports pagination.
get_estimate
Retrieve comprehensive estimate details by ID including customer info, line items with products/services, amounts, transaction date, expiration date, and acceptance status.
create_estimate
Create sales estimate for customer with line items. Specify customer, line items with products/services, transaction date, optional expiration date, and customer memo.
update_estimate
Update estimate with new line items, dates, customer memo, or addresses. Uses optimistic locking with sync_token.
delete_estimate
Delete estimate by ID permanently. Uses optimistic locking with sync_token.
send_estimate
Send estimate via email to customer. Specify estimate ID, recipient email address, and optional subject line and message body.
query_invoices
Query invoices using SQL-like syntax with filters for customer, status, dates, and amounts. Parameters: query (SQL filter), max_results (1-1000), start_position, customer_id, status, start_date, end_date (YYYY-MM-DD). Supports pagination for large datasets.
get_invoice
Retrieve comprehensive invoice details by ID including customer info, line items with quantities and amounts, payment status, delivery info, tax calculations, and financial totals. Parameters: invoice_id (required string). Essential for invoice management and financial analysis.
create_invoice
Create invoice with line items, customer details, and financial settings. Parameters: customer_id (required), line_items (required array), txn_date (YYYY-MM-DD), due_date, doc_number, private_note, customer_memo, email_address. Auto-calculates taxes and balances.
update_invoice
Modify existing invoice with updated line items, financial details, and settings. Supports updating customer refs, line items, dates, invoice numbers, and notes. Uses optimistic locking with sync_token. Parameters: id (required), sync_token (required), customer_id, line_items, txn_date, due_date, doc_number. Cannot update paid/voided invoices. Requires OAuth 2.0 with write permissions.
void_invoice
Void invoice while maintaining audit trail. Preserves historical records but removes from accounts receivable. Parameters: id (required), sync_token (required). Cannot void paid invoices.
send_invoice
Send invoice via email with customizable subject and message. Includes PDF and payment portal links. Parameters: invoice_id (required), email_address (required), subject, message.
query_items
Query items using SQL-like syntax with flexible filtering and pagination support. Search products and services by type (Service/Inventory/NonInventory/Category), active status, and custom SQL filters. Returns comprehensive item details including pricing, accounts, inventory tracking, and SKU information. Parameters: query (SQL filter), max_results (1-1000), start_position, item_type, active_only. Essential for inventory management, invoice line items, and product catalog operations. Requires OAuth 2.0 with com.intuit.quickbooks.accounting scope.
get_item
Retrieve comprehensive item details by ID including name, description, SKU, unit price, purchase cost, income/expense accounts, inventory tracking, and quantity on hand. Parameters: item_id (required string). Essential for invoice line item details, inventory checks, and price lookups. Requires OAuth 2.0 with com.intuit.quickbooks.accounting scope.
create_item
Create item for products/services. Requires name, type (Service/Inventory/NonInventory/Category), and type-specific accounts. Inventory needs asset_account_id. Supports inventory tracking, SKU, pricing. Type cannot be changed after creation. Essential for product catalogs and invoices.
update_item
Update item name, description, SKU, pricing, accounts, or status. Requires id and sync_token for optimistic locking. Sparse update (only provided fields change). Type cannot change after creation. Use Inventory Adjustments for quantity changes. Essential for price and status updates.
delete_item
Delete an item by marking it as inactive (soft delete). Items cannot be permanently deleted if they have been used in transactions. Inactive items are hidden from dropdowns but remain in historical records. Parameters: item_id (required), sync_token (required). Essential for item lifecycle management and catalog cleanup. Requires OAuth 2.0 with com.intuit.quickbooks.accounting scope.
query_payments
Query payments using SQL-like syntax with filters for customer, date range, and amount. Parameters: query (SQL filter), max_results (1-1000), start_position, customer_id, txn_date_start, txn_date_end. Supports pagination.
get_payment
Retrieve comprehensive payment details by ID including customer info, payment method, line items showing invoice applications, amounts applied and unapplied.
create_payment
Create payment record for customer against invoices. Specify total amount, customer, payment method, and line items linking to invoices. Auto-calculates unapplied amounts.
update_payment
Update payment with new amount, method, or invoice applications. Uses optimistic locking with sync_token.
delete_payment
Delete payment by ID. Uses optimistic locking with sync_token.
validate_credential
Validate QuickBooks Online credentials by making a test API call. Returns success status and message. Use this to verify credentials and realm ID are valid.
query_vendors
Query vendors using SQL-like syntax with filters for active status and name. Parameters: query (SQL filter), max_results (1-1000), start_position, active_only. Supports pagination.
get_vendor
Retrieve comprehensive vendor details by ID including contact information, addresses, email, phone numbers, tax identifier, balance, and 1099 status.
create_vendor
Create vendor record with display name, contact details, billing address, email, phone, tax identifier, and 1099 settings. Display name is required.
update_vendor
Update vendor with new contact details, address, email, phone, tax info, or active status. Uses optimistic locking with sync_token.
delete_vendor
Delete vendor by ID. Uses optimistic locking with sync_token.
How to set up Merge Agent Handler
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}FAQs on using Merge's QuickBooks Online MCP server
FAQs on using Merge's QuickBooks Online MCP server
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
