QuickBooks Official

Frequently asked questions

What does the QuickBooks MCP server do?

QuickBooks Online MCP Server > A comprehensive Model Context Protocol (MCP) server for QuickBooks Online Quick Start Available Tools Authentication Documentation > --- Overview This MCP server provides complete QuickBooks Online API integration for Claude Code and other MCP-compatible clients. It includes full CRUD operations for 29 entity types and 11 financial reports, giving you comprehensive access to QuickBooks Online functionality. Key Features 145 Total Tools - Complete coverage of QuickBooks Online API 29 Entity Types - Full CRUD operations (Create, Read, Update, Delete, Search) 11 Financial Reports - Balance Sheet, P&L, Cash Flow, and more OAuth 2.0 Authentication - Secure token-based authentication TypeScript - Full type safety with Zod validation Tested - Jest test suite with ESM support > Note: this is a local MCP server. It runs as a stdio subprocess on the developer's or partner's machine and authenticates to a QuickBooks Online company. > Before you start: This MCP server is easy to run once authenticated, but QuickBooks Online integration is gated by Intuit's OAuth app setup. You must register an app on the Intuit Developer Portal and complete a one-time, browser-based OAuth handshake. Sandbox supports redirect URIs; production requires a public HTTPS callback for the initial authorization. After that initial handshake, the server runs locally without further browser interaction (until the 100-day refresh window lapses). See Authentication for full details. --- Quick Start Installation Configuration Copy the template .env.example to .env in the root directory and fill in your values: .env is gitignored so your real credentials stay local. > Read-only or containerized installs: the server reads .env at startup and writes the rotated refresh token back to it on each refresh. When the installed module sits on a read-only filesystem (a container with a read-only root, an immutable/Nix install), set QUICKBOOKS TOKEN STORE PATH to an absolute, writable path for both operations. A per-tenant host can also point each connection at its own isolated token file this way. Three things to know: it must be set in the host process env (e.g. the env block of your MCP server config) — setting it inside .env has no effect, because the path is resolved before .env is read; it must be an absolute path (the server refuses to start otherwise); and when set, the package's own .env is not read at all, so any file-based config (including credentials) must live in the file it points to. Claude Code Integration Add to your Claude Code MCP configuration: Set any of the DISABLE flags to "true" to prevent that category of tools from being registered. Read tools ( get , search ) are always available. --- Available Tools Entities Complete CRUD operations are available for all entity types: Entity Create Get Update Delete Search -------- :------: :---: :------: :------: :------: Customer ✅ ✅ ✅ ✅ ✅ Invoice ✅ ✅ ✅ ✅ ✅ Estimate ✅ ✅ ✅ ✅ ✅ Bill ✅ ✅ ✅ ✅ ✅ Vendor ✅ ✅ ✅ ✅ ✅ Employee ✅ ✅ ✅ ✅ ✅ Account ✅ ✅ ✅ - ✅ Item ✅ ✅ ✅ ✅ ✅ Journal Entry ✅ ✅ ✅ ✅ ✅ Bill Payment ✅ ✅ ✅ ✅ ✅ Purchase ✅ ✅ ✅ ✅ ✅ Payment ✅ ✅ ✅ ✅ ✅ Sales Receipt ✅ ✅ ✅ ✅ ✅ Credit Memo ✅ ✅ ✅ ✅ ✅ Refund Receipt ✅ ✅ ✅ ✅ ✅ Purchase Order ✅ ✅ ✅ ✅ ✅ Vendor Credit ✅ ✅ ✅ ✅ ✅ Deposit ✅ ✅ ✅ ✅ ✅ Transfer ✅ ✅ ✅ ✅ ✅ Time Activity ✅ ✅ ✅ ✅ ✅ Class ✅ ✅ ✅ - ✅ Department ✅ ✅ ✅ - ✅ Term ✅ ✅ ✅ - ✅ Payment Method ✅ ✅ ✅ - ✅ Tax Code - ✅ - - ✅ Tax Rate - ✅ - - ✅ Tax Agency - ✅ - - ✅ Company Info - ✅ ✅ - - Attachable ✅ ✅ ✅ ✅ ✅ Reports Report Tool Name Description -------- ----------- ------------- Balance Sheet get balance sheet Assets, liabilities, and equity snapshot Profit & Loss get profit and loss Income and expenses over a period Cash Flow get cash flow Cash inflows and outflows Trial Balance get trial balance Debit and credit balances General Ledger get general ledger Complete transaction history Customer Sales get customer sales Sales by customer Aged Receivables get aged receivables Outstanding customer invoices Aged Receivables Detail get aged receivables detail Detailed aging breakdown Customer Balance get customer balance Current customer balances Aged Payables get aged payables Outstanding vendor bills Vendor Expenses get vendor expenses Expenses by vendor --- Tool Reference > > >Customer Tools > > Tool Description ------ ------------- create customer Create a new customer get customer Get customer by ID update customer Update customer details delete customer Delete a customer search customers Search customers with filters > > > >Invoice Tools > > Tool Description ------ ------------- create invoice Create a new invoice get invoice Get invoice by ID update invoice Update invoice details delete invoice Delete/void an invoice search invoices Search invoices with filters get invoice pdf Download an invoice as a PDF (inline base64, or to disk when QBO PDF OUTPUT DIR is set) > > > >Payment Tools > > Tool Description ------ ------------- create payment Record a customer payment get payment Get payment by ID update payment Update payment details delete payment Void a payment search payments Search payments with filters > > > >Bill & Vendor Tools > > Tool Description ------ ------------- create bill Create a new bill get bill Get bill by ID update bill Update bill details delete bill Delete a bill search bills Search bills with filters create vendor Create a new vendor get vendor Get vendor by ID update vendor Update vendor details delete vendor Delete a vendor search vendors Search vendors with filters create bill payment Create a bill payment get bill payment Get bill payment by ID update bill payment Update bill payment delete bill payment Delete a bill payment search bill payments Search bill payments > > > >Sales Receipt & Credit Memo Tools > > Tool Description ------ ------------- create sales receipt Create a sales receipt get sales receipt Get sales receipt by ID update sales receipt Update sales receipt delete sales receipt Void a sales receipt search sales receipts Search sales receipts create credit memo Create a credit memo get credit memo Get credit memo by ID update credit memo Update credit memo delete credit memo Void a credit memo search credit memos Search credit memos create refund receipt Create a refund receipt get refund receipt Get refund receipt by ID update refund receipt Update refund receipt delete refund receipt Void a refund receipt search refund receipts Search refund receipts > > > >Banking Tools > > Tool Description ------ ------------- create deposit Create a bank deposit get deposit Get deposit by ID update deposit Update deposit details delete deposit Delete a deposit search deposits Search deposits create transfer Create an account transfer get transfer Get transfer by ID update transfer Update transfer details delete transfer Delete a transfer search transfers Search transfers > > > >Purchase Order & Vendor Credit Tools > > Tool Description ------ ------------- create purchase order Create a purchase order get purchase order Get purchase order by ID update purchase order Update purchase order delete purchase order Delete a purchase order search purchase orders Search purchase orders create vendor credit Create a vendor credit get vendor credit Get vendor credit by ID update vendor credit Update vendor credit delete vendor credit Delete a vendor credit search vendor credits Search vendor credits > > > >Time Tracking Tools > > Tool Description ------ ------------- create time activity Create a time activity get time activity Get time activity by ID update time activity Update time activity delete time activity Delete a time activity search time activities Search time activities > > > >Classification Tools > > Tool Description ------ ------------- create class Create a class get class Get class by ID update class Update class details search classes Search classes create department Create a department get department Get department by ID update department Update department search departments Search departments > > > >Settings Tools > > Tool Description ------ ------------- create term Create a payment term get term Get term by ID update term Update term details search terms Search terms create payment method Create a payment method get payment method Get payment method by ID update payment method Update payment method search payment methods Search payment methods get preferences Get company accounting and feature preferences > > > >Tax Tools > > Tool Description ------ ------------- get tax code Get tax code by ID search tax codes Search tax codes get tax rate Get tax rate by ID search tax rates Search tax rates get tax agency Get tax agency by ID search tax agencies Search tax agencies > > > >Company & Attachments > > Tool Description ------ ------------- get company info Get company information update company info Update company info create attachable Create an attachment get attachable Get attachment by ID update attachable Update attachment delete attachable Delete an attachment search attachables Search attachments > --- Authentication This server uses OAuth 2.0 to authenticate to a QuickBooks Online company. You'll set up an app on the Intuit Developer Portal and connect it to either a sandbox (for development) or your production QBO company. Important: Sandbox vs Production Mode When to use Redirect URI accepted Setup difficulty ------ ------------- ------------------------ ------------------ Sandbox Development, testing, demos works Easy Production Real company data Localhost rejected — must be a public HTTPS URL Harder (see below) If you only want to read your own company's data, you still need to set up an app — Intuit does not offer per-user API keys. There is no shortcut around the OAuth + app-creation flow. Sandbox Setup (recommended for first run) Go to the Intuit Developer Portal and create a new app Open the app → Settings (left sidebar) → Redirect URIs → add: Get your Client ID and Client Secret from the app's Keys & Credentials page (Development keys) Create or use a sandbox company under the Sandbox top-level menu item in the dev portal Set QUICKBOOKS ENVIRONMENT=sandbox in your .env Run npm run auth to complete the OAuth handshake — your browser will open, you sign in to the sandbox company, tokens are saved to .env Production Setup The Intuit Developer Portal rejects redirect URIs in production mode — every contributor hits this. Two known workarounds: ngrok tunnel (most common): run ngrok http 8000 , then on your Intuit app go to Settings → Redirect URIs and add the generated https:// >.ngrok-free.app/callback URL. Use that URL for the OAuth handshake, then revert to localhost afterwards. Deploy a small public callback handler (e.g., on a VPS or serverless function) that captures the auth code and hands it back to your local setup. More involved; only needed if you can't use ngrok. After completing the production OAuth handshake, the refresh token is what matters — once it's in .env , you no longer need the public redirect URL for day-to-day use. Refresh tokens auto-rotate; the server persists the new token on each refresh. Once you have tokens Common pitfalls .env loaded from the wrong directory. The server resolves .env relative to the compiled module, not your shell's CWD. If you launch via Claude Desktop, this matters — make sure you're on current main . Redirect URI mismatch. The URI you register in the Intuit portal must match exactly — protocol, host, port, path. . --- Development Building Testing The test suite includes 396 tests with 100% code coverage across all metrics (statements, branches, functions, lines). Project Structure --- Documentation Document Description ---------- ------------- CHANGELOG.md Version history and all changes docs/ARCHITECTURE.md System architecture, patterns, and design decisions docs/TESTING.md Testing strategy, ESM patterns, and coverage guide --- Error Handling If you encounter connection errors: Verify all environment variables are set correctly Check that tokens are valid and not expired Ensure the QuickBooks app has the correct redirect URIs For sandbox testing, use QUICKBOOKS ENVIRONMENT=sandbox --- Contributing Contributions are welcome! Please feel free to submit a Pull Request. Tool naming convention All tool names must follow the {verb} {entity} convention using underscores. The verb prefix determines CRUD Restriction Mode behaviour: Prefix Category Suppressed by -------- ---------- --------------- create WRITE QUICKBOOKS DISABLE WRITE=true update UPDATE QUICKBOOKS DISABLE UPDATE=true delete DELETE QUICKBOOKS DISABLE DELETE=true get , search , read READ never New tools that do not follow this convention will not be correctly categorised and may appear or be suppressed unexpectedly. --- License MIT License - see LICENSE for details. --- Acknowledgments Based on Intuit's QuickBooks Online MCP Server Built with the Model Context Protocol

How do I install QuickBooks?

Use the client configuration shown on this page and restart your MCP client.

Is QuickBooks free to use?

The MCP server itself is free to install. The source is public on https://github.com/intuit/quickbooks-online-mcp-server. Any third-party service it calls may require its own API key and account.

Which clients support QuickBooks?

Any MCP-compatible client can use it, including Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and custom agents.