Summary
Connects Claude directly to QuickBooks Online via the Intuit REST API with OAuth2 authentication. The free tier gives you read access to invoices, expenses, account balances, transactions, and customer data. Premium tier adds P&L, balance sheet, cash flow reports, AR/AP aging, and write operations like creating invoices, recording payments, and logging expenses. Tokens are encrypted at rest with auto-refresh, and rate limiting is built in. Setup requires creating a QuickBooks developer app, running an OAuth flow to get your realm ID, and dropping credentials into your Claude Desktop config. If you're doing bookkeeping through natural language instead of clicking through the QuickBooks UI, this handles the API plumbing.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
18 tools
QUICKBOOKS_CREATE_ACCOUNTCreate a new account in QuickBooks with the given parameters.4 params
Create a new account in QuickBooks with the given parameters.
Parameters* required
namestringUser recognizable name for the Account. Account.Name attribute must not contain double quotes (") or colon (:).
account_typestringType of the account to be createdone of
Bank · Other Current Asset · Fixed Asset · Other Asset · Accounts Receivable · Equityaccount_numberstringUser-defined account number to help the user in identifying the account within the chart-of-accounts and in deciding what should be posted to the account. must not contain colon (:). For France locales:
account_sub_typestringSub-type of the account. Must use exact enum values (no spaces/slashes). Examples: 'AdvertisingPromotional' (NOT 'Advertising/Promotional'), 'Checking', 'Inventory', 'OtherCurrentAssets', 'Vehicles', 'RetainedEarnings', 'Insurance', 'InterestEarned'. See QuickBooks API docs for complete list.one of
CashOnHand · Checking · MoneyMarket · RentsHeldInTrust · Savings · TrustAccountsQUICKBOOKS_CREATE_CUSTOMERCreate a new customer in QuickBooks with the given parameters.6 params
Create a new customer in QuickBooks with the given parameters.
Parameters* required
titlestringTitle of the person (max 16 characters - keep it short like 'Mr.', 'Dr.', 'CEO'). This tag supports i18n, all locales. The DisplayName attribute or at least one of Title, GivenName, MiddleName, FamilyName, Suffix, or FullyQualifiedName attributes are required during create.
suffixstringSuffix of the name. For example, Jr. The DisplayName attribute or at least one of Title, GivenName, MiddleName, FamilyName, or Suffix attributes is required for object create.
given_namestringGiven name or first name of a person. The DisplayName attribute or at least one of Title, GivenName, MiddleName, FamilyName, or Suffix attributes is required for object create.
family_namestringFamily name or the last name of the person. The DisplayName attribute or at least one of Title, GivenName, MiddleName, FamilyName, or Suffix attributes is required for object create.
middle_namestringMiddle name of the person. The person can have zero or more middle names. The DisplayName attribute or at least one of Title, GivenName, MiddleName, FamilyName, or Suffix attributes is required for object create.
display_namestringThe name as displayed. Must be unique across all Customer, Vendor, and Employee objects. Cannot be removed with sparse update. If not supplied, the system generates DisplayName by concatenating customer name components supplied in the request from the following list: Title, GivenName, MiddleName, FamilyName, and Suffix.
QUICKBOOKS_CREATE_EMPLOYEECreate a new employee in QuickBooks.3 params
Create a new employee in QuickBooks.
Parameters* required
given_namestringGiven name or Family name of a person. At least one of `given_name` or `family_name` attributes is required.
family_namestringFamily name or the last name of the person. At least one of `given_name` or `family_name` attributes is required.
primary_addrobjectRepresents the physical street address for this employee. If QuickBooks Payroll is enabled for the company, the following PhysicalAddress fields are required: City, CountrySubDivisionCode, PostalCode.
QUICKBOOKS_CREATE_INVOICETool to create a new invoice in QuickBooks. Use after confirming customer and item details.3 params
Tool to create a new invoice in QuickBooks. Use after confirming customer and item details.
Parameters* required
linesarrayList of invoice line item objects. Each item must include at least: 'DetailType', 'Amount', and 'SalesItemLineDetail' with an 'ItemRef.value'.
customer_idstringID of the customer to invoice (CustomerRef.value)
minorversionintegerOptional minorversion query parameter to control API behavior
QUICKBOOKS_CREATE_VENDORCreate a new vendor in QuickBooks with the given details.6 params
Create a new vendor in QuickBooks with the given details.
Parameters* required
titlestringTitle of the person (max 16 characters - keep it short like 'Mr.', 'Dr.', 'CEO'). This tag supports i18n, all locales. The DisplayName attribute or at least one of Title, GivenName, MiddleName, FamilyName, Suffix, or FullyQualifiedName attributes are required during create.
suffixstringSuffix of the name. For example, Jr. The DisplayName attribute or at least one of Title, GivenName, MiddleName, FamilyName, or Suffix attributes is required for object create.
given_namestringGiven name or first name of a person. The DisplayName attribute or at least one of Title, GivenName, MiddleName, FamilyName, or Suffix attributes is required for object create.
family_namestringFamily name or the last name of the person. The DisplayName attribute or at least one of Title, GivenName, MiddleName, FamilyName, or Suffix attributes is required for object create.
middle_namestringMiddle name of the person. The person can have zero or more middle names. The DisplayName attribute or at least one of Title, GivenName, MiddleName, FamilyName, or Suffix attributes is required for object create.
display_namestringThe name as displayed. Must be unique across all Customer, Vendor, and Employee objects. Cannot be removed with sparse update. If not supplied, the system generates DisplayName by concatenating customer name components supplied in the request from the following list: Title, GivenName, MiddleName, FamilyName, and Suffix.
QUICKBOOKS_CUSTOMER_BALANCE_DETAILGenerate a balance detail report for a customer in QuickBooks with the given customer ID.13 params
Generate a balance detail report for a customer in QuickBooks with the given customer ID.
Parameters* required
arpaidstringStatus of the balance.one of
All · Paid · UnpaidcolumnsstringColumn types to be shown in the report. Supported Values: bill_addr, create_by, create_date, cust_bill_email, cust_comp_name, cust_msg, cust_phone_other, cust_tel, cust_name, deliv_addr, doc_num*, due_date*, last_mod_by, last_mod_date, memo*, sale_sent_state, ship_addr, ship_date, ship_via, term_name, tracking_num, tx_date*, txn_type*. Additional columns with custom fields enabled: sales_cust1, sales_cust2, sales_cust3. Additional columns with location tracking enabled: dept_name*
custom1stringFilter by the specified custom field as defined by the CustomField attribute in transaction entities where supported. Supported Values: Name of custom field.
shipviastringFilter by the shipping method as stored in Invoice.ShipMethodRef.Name.
sort_bystringThe column type used in sorting report rows. Specify a column type as defined with the columns query parameter.
term_idsarrayOne or more comma separated term IDs. Filters report contents based on term or terms supplied.
sort_orderstringThe sort order.one of
ascend · descendend_duedatestringThe range of dates over which receivables are due, in the format YYYY-MM-DD. start_duedate must be less than end_duedate. If not specified, all data is returned.
report_datestringStart date to use for the report, in the format YYYY-MM-DD.
aging_methodstringThe date upon which aging is determined.one of
Report_Date · Currentcustomer_idsarrayOne or more comma separated customer IDs. Filters report contents to include information for specified customers.
start_duedatestringThe range of dates over which receivables are due, in the format YYYY-MM-DD. start_duedate must be less than end_duedate. If not specified, all data is returned.
department_idsarrayOne or more comma separated department IDs. Filters report contents to include information for specified departments if so configured in the company file.
QUICKBOOKS_CUSTOMER_BALANCE_REPORTGenerate a balance report for a customer in QuickBooks with the given customer ID.8 params
Generate a balance report for a customer in QuickBooks with the given customer ID.
Parameters* required
arpaidstringSupported Values: All, Paid, Unpaidone of
All · Paid · Unpaiddate_macrostringPredefined date range. Use if you want the report to cover a standard report date range; otherwise, use the start_date and end_date to cover an explicit report date range.one of
Today · Yesterday · This Week · Last Week · This Week-to-date · Last Week-to-datesort_orderstringThe sort order.one of
ascend · descendreport_datestringStart date to use for the report, in the format YYYY-MM-DD.
customer_idsarrayFilters report contents to include information for specified customers. Supported Values: One or more comma separated customer IDs as returned in the attribute, Customer.Id, of the Customer object response code.
department_idsarrayOne or more comma separated department IDs. Filters report contents to include information for specified departments if so configured in the company file.
accounting_methodstringThe accounting method used in the report. one of
Cash · Accrualsummarize_column_bystringThe criteria by which to group the report results.one of
Total · Month · Week · Days · Quarter · YearQUICKBOOKS_LIST_INVOICESTool to list invoices via QuickBooks Query endpoint. Use when retrieving invoices with optional pagination and custom fields.3 params
Tool to list invoices via QuickBooks Query endpoint. Use when retrieving invoices with optional pagination and custom fields.
Parameters* required
fieldsarrayList of fields to select in the query. Defaults to ['Id','SyncToken','DocNumber','TotalAmt','Balance','TxnDate'].
max_resultsintegerMaximum number of records to return; default 50, max 1000.default: 50
start_positionintegerStarting position for pagination within the result set. Default is 1.default: 1
QUICKBOOKS_QUERY_ACCOUNTQuery an account in QuickBooks with the given parameters.1 params
Query an account in QuickBooks with the given parameters.
Parameters* required
querystringQuery to be executed
QUICKBOOKS_READ_ACCOUNTRead an account in QuickBooks with the given account ID.1 params
Read an account in QuickBooks with the given account ID.
Parameters* required
account_idstringID of the account to be read
QUICKBOOKS_READ_CUSTOMERRead a customer in QuickBooks with the given customer ID.1 params
Read a customer in QuickBooks with the given customer ID.
Parameters* required
customer_idstringID of the customer to be read
QUICKBOOKS_READ_EMPLOYEERead an employee's details in QuickBooks with the given employee ID.1 params
Read an employee's details in QuickBooks with the given employee ID.
Parameters* required
employee_idstringThe ID of the employee to be read.
QUICKBOOKS_READ_INVOICETool to fetch a QuickBooks invoice by ID or the most recent if no ID provided. Use when needing full invoice details including metadata and sync token.2 params
Tool to fetch a QuickBooks invoice by ID or the most recent if no ID provided. Use when needing full invoice details including metadata and sync token.
Parameters* required
invoice_idstringID of the invoice to read; if not provided, fetches the latest invoice
minorversionintegerAPI minor version to use for the request
QUICKBOOKS_READ_VENDORRead a vendor in QuickBooks with the given vendor ID.1 params
Read a vendor in QuickBooks with the given vendor ID.
Parameters* required
vendor_idstringID of the vendor to be read
QUICKBOOKS_UPDATE_FULL_INVOICETool to fully replace an Invoice. Use when you need to update all aspects of an existing invoice in a single operation.3 params
Tool to fully replace an Invoice. Use when you need to update all aspects of an existing invoice in a single operation.
Parameters* required
invoiceobjectFull Invoice JSON payload to update; must include Id and SyncToken. Any writable field omitted will be cleared. Do not set sparse=true.
requestidstringOptional idempotency key (<=50 chars) to prevent duplicate writes on retries.
minorversionintegerOptional QuickBooks API minorversion to access newer fields (e.g., 63).
QUICKBOOKS_UPDATE_SPARSE_INVOICETool to perform a sparse update of an existing invoice. Use when you need to update only specific invoice fields without overwriting other data.1 params
Tool to perform a sparse update of an existing invoice. Use when you need to update only specific invoice fields without overwriting other data.
Parameters* required
invoiceobjectInvoice object containing Id, SyncToken, sparse flag, and fields to update
QUICKBOOKS_VENDOR_BALANCE_DETAILGenerate a balance detail report for a vendor in QuickBooks with the given vendor ID.12 params
Generate a balance detail report for a vendor in QuickBooks with the given vendor ID.
Parameters* required
appaidstringStatus of the balance.one of
All · Paid · Unpaidsort_bystringThe column type used in sorting report rows. Specify a column type as defined with the columns query parameter.
term_idsarrayOne or more comma separated term IDs. Filters report contents based on term or terms supplied.
date_macrostringPredefined date range. Use if you want the report to cover a standard report date range; otherwise, use the start_date and end_date to cover an explicit report date range.one of
Today · Yesterday · This Week · Last Week · This Week-to-date · Last Week-to-datesort_orderstringThe sort order.one of
ascend · descendvendor_idsarrayOne or more comma separated vendor IDs. Filters report contents to include information for specified vendors.
end_duedatestringThe range of dates over which receivables are due, in the format YYYY-MM-DD. start_duedate must be less than end_duedate. If not specified, all data is returned.
report_datestringStart date to use for the report, in the format YYYY-MM-DD.
duedate_macrostringPredefined date range of due dates for balances to include in the report; otherwise, use the start_duedate and end_duedate to cover an explicit report date range. one of
Today · Yesterday · This Week · Last Week · This Week-to-date · Last Week-to-datestart_duedatestringThe range of dates over which receivables are due, in the format YYYY-MM-DD. start_duedate must be less than end_duedate. If not specified, all data is returned.
department_idsarrayOne or more comma separated department IDs. Filters report contents to include information for specified departments if so configured in the company file.
accounting_methodstringThe accounting method used in the report.one of
Cash · AccrualQUICKBOOKS_VENDOR_BALANCE_REPORTGet the balance report of a vendor in QuickBooks with the given vendor ID.9 params
Get the balance report of a vendor in QuickBooks with the given vendor ID.
Parameters* required
qzurlstringSpecifies whether Quick Zoom URL information should be generated for rows in the report.
appaidstringStatus of the balance.one of
All · Paid · Unpaiddate_macrostringPredefined date range. Use if you want the report to cover a standard report date range; otherwise, use the start_date and end_date to cover an explicit report date range.one of
Today · Yesterday · This Week · Last Week · This Week-to-date · Last Week-to-datesort_orderstringThe sort order.one of
ascend · descendvendor_idsarrayFilters report contents to include information for specified vendors. Supported Values: One or more comma separated vendor IDs as returned in the attribute, Vendor.Id, of the Vendor object response code.
report_datestringStart date to use for the report, in the format YYYY-MM-DD.
department_idsarrayOne or more comma separated department IDs. Filters report contents to include information for specified departments if so configured in the company file.
accounting_methodstringThe accounting method used in the report. one of
Cash · Accrualsummarize_column_bystringThe criteria by which to group the report results.one of
Total · Month · Week · Days · Quarter · YearQuickBooks MCP Server
Connect Claude Desktop and Claude Code to QuickBooks Online for natural-language accounting. Ask questions about invoices, expenses, reports, and more using plain English.
What is this?
An MCP (Model Context Protocol) server that gives Claude direct access to your QuickBooks Online data. Instead of logging into QuickBooks and clicking through reports, just ask Claude:
"Show me all overdue invoices sorted by amount" "What's our P&L this quarter?" "Create an invoice for Acme Corp for $2,500"
The server handles OAuth authentication, API calls, rate limiting, and data formatting.
Quick Start
1. Install
pip install quickbooks-mcp
Or install from source:
git clone https://github.com/nyxtools/quickbooks-mcp-server.git
cd quickbooks-mcp-server
pip install -e .
2. Create a QuickBooks Developer App
- Go to developer.intuit.com
- Create an app and select QuickBooks Online and Payments
- Under Keys & OAuth, note your Client ID and Client Secret
- Add
http://localhost:8080/callbackas a Redirect URI
3. Set Environment Variables
export QBO_CLIENT_ID='your_client_id'
export QBO_CLIENT_SECRET='your_client_secret'
4. Run OAuth Setup
python scripts/setup_oauth.py
This opens your browser, authorizes with QuickBooks, and stores tokens locally (encrypted). Note the Realm ID it prints at the end.
export QBO_REALM_ID='your_realm_id'
5. Configure Claude Desktop
Add to your Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"quickbooks": {
"command": "quickbooks-mcp",
"env": {
"QBO_CLIENT_ID": "your_client_id",
"QBO_CLIENT_SECRET": "your_client_secret",
"QBO_REALM_ID": "your_realm_id"
}
}
}
}
Config file locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
6. Start Using It
Restart Claude Desktop and try:
"What are my current bank account balances?"
All 19 Tools
Free Tier (9 tools)
| Tool | Description |
|---|---|
list_invoices | List and filter invoices by status, date, customer |
get_invoice_details | Full invoice details with line items and payment history |
get_overdue_invoices | All overdue invoices sorted by days past due |
list_expenses | List expenses with date, vendor, amount, and category filters |
get_top_expenses | Top expenses grouped by category or vendor for any period |
get_account_balances | Current balances for Bank, Credit Card, or all accounts |
get_account_transactions | Recent transactions for any account with date filters |
search_customers | Search customers by name or email with contact info |
get_customer_summary | Customer financial summary: invoiced, paid, outstanding |
Premium Tier (10 tools) -- $29/month
| Tool | Description |
|---|---|
get_profit_and_loss | P&L report for any period with income/expense breakdown |
get_balance_sheet | Balance sheet as of any date (assets, liabilities, equity) |
get_cash_flow | Cash flow statement (operating, investing, financing) |
get_accounts_receivable_aging | AR aging by customer (current/30/60/90+ days) |
get_accounts_payable_aging | AP aging by vendor (current/30/60/90+ days) |
create_invoice | Create invoices with line items, due dates, and memos |
record_payment | Record payments against invoices with method and reference |
create_expense | Record expenses with vendor, amount, category, and date |
get_financial_health | Key ratios: current ratio, DSO, burn rate, runway |
compare_periods | Side-by-side period comparison with % changes |
Get a premium license at nyxtools.dev/quickbooks-mcp
Set it in your environment:
export LICENSE_KEY='your_license_key'
Usage Examples
Invoices
"Show me all invoices from January" "Which invoices are overdue? Show me the worst ones first" "Get the details for invoice #1042" "Show me open invoices for Acme Corp"
Expenses
"What did we spend this month?" "Show me our top 10 expense categories this quarter" "How much have we spent at Amazon this year?"
Accounts
"What are our bank balances?" "Show me the last 20 transactions in checking" "What's the balance on our company credit card?"
Customers
"Find the customer John Smith" "Give me a financial summary for customer 456" "Search for customers with outstanding balances"
Reports (Premium)
"Show me the P&L for this quarter" "Pull up the balance sheet" "How's our cash flow this month?" "Show me the AR aging report" "Who are our slowest-paying customers?"
Write Operations (Premium)
"Create an invoice for customer 123: Website Design $2,500, Hosting $150/month, due net-30" "Record a $1,000 check payment on invoice #1042" "Record a $250 expense to Office Depot for supplies, paid by credit card on March 15"
Analytics (Premium)
"How healthy are our finances? Show me key ratios" "Compare this month to last month" "How did this quarter compare to the same quarter last year?"
Configuration
All configuration is via environment variables:
| Variable | Required | Default | Description |
|---|---|---|---|
QBO_CLIENT_ID | Yes | QuickBooks OAuth2 Client ID | |
QBO_CLIENT_SECRET | Yes | QuickBooks OAuth2 Client Secret | |
QBO_REALM_ID | Yes | QuickBooks Company/Realm ID | |
QBO_REDIRECT_URI | No | http://localhost:8080/callback | OAuth redirect URI |
LICENSE_KEY | No | Premium license key | |
QBO_SANDBOX | No | false | Use sandbox environment |
TOKEN_STORE_PATH | No | ~/.quickbooks-mcp/tokens.json | Token storage location |
LOG_LEVEL | No | INFO | Logging level |
Security
- Tokens encrypted at rest using machine-specific keys (Fernet + PBKDF2)
- Tokens auto-refresh -- access tokens last 60 min, refresh tokens 100 days
- No credentials stored in code -- all secrets via environment variables
- Rate limiting built in to respect QuickBooks API throttles
- Input sanitization on all query parameters to prevent injection
Development
# Clone and install with dev dependencies
git clone https://github.com/nyxtools/quickbooks-mcp-server.git
cd quickbooks-mcp-server
pip install -e ".[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=quickbooks_mcp
# Lint
ruff check src/ tests/
# Type check
mypy src/
Project Structure
quickbooks-mcp-server/
src/quickbooks_mcp/
auth/ # OAuth2 flow and encrypted token storage
client/ # QBO REST API client with rate limiting
tools/ # MCP tool implementations (19 tools)
utils/ # Money (Decimal), formatting, license validation
server.py # MCP server setup and tool registration
config.py # Environment-based configuration
scripts/
setup_oauth.py # Interactive OAuth setup
examples/ # Config examples and usage guide
tests/ # Pytest test suite
Troubleshooting
"No QuickBooks tokens found"
Run the OAuth setup:
python scripts/setup_oauth.py
"Token refresh failed"
Your refresh token may have expired. Re-run OAuth setup.
"QuickBooks API error (HTTP 403)"
Verify your app has com.intuit.quickbooks.accounting scope.
"Rate limited by QuickBooks"
The server handles rate limiting automatically. If you see this error, wait 60 seconds.
"This is a premium feature"
Some tools require a license key. Get one here or set LICENSE_KEY in your environment.
Sandbox Mode
For testing without affecting real data:
export QBO_SANDBOX=true
Use your Development keys (not Production) from the Intuit developer dashboard.
License
MIT License. See LICENSE for details.
Copyright (c) 2026 NyxTools
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Categories
Registryactive
Packagequickbooks-mcp
TransportSTDIO
UpdatedMar 25, 2026
