QuickBooks MCP Server
This server lets Claude Desktop answer plain-English questions about a QuickBooks Online company using live, read-only data.
Get receivables aging: who owes money, how much, and how overdue.
Get payables aging: bills owed to vendors and upcoming payment obligations.
Get profit and loss: income, expenses, and net profit over a period.
Get balance sheet: assets, liabilities, equity, and cash position.
Find customers or vendors by name, with contact details and balances.
Get company info: name, address, and fiscal year.
Run arbitrary read-only QuickBooks SELECT queries for anything else.
Describe schema: list queryable entities, fields, and query dialect rules.
Read-only by design: only GET requests are issued, with no code path that can write to QuickBooks.
Runs locally and keeps credentials outside the repository, connecting to your own sandbox or production company.
Read-only integration with QuickBooks Online, providing tools to query receivables, payables, profit and loss, balance sheet, contacts, and run arbitrary queries against the QuickBooks API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@QuickBooks MCP Server Who owes us money and how overdue is it?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
QuickBooks MCP server — local, read-only
Ask Claude Desktop questions about a QuickBooks Online company in plain English and get answers from the live books.
RESPONSES WILL BE DIFFERENT THAN THOSE WRITTEN HERE: EXAMPLE FIGURES ARE DERIVED FROM YOUR OWN SANDBOX
You: Who owes us money and how overdue is it?
Claude: Sandbox Company US 4768 has $5,281.52 outstanding across 20 open invoices. Most of it isn't late yet — $3,756.02 is still current. Of the $1,525.50 that is overdue, the worst is Red Rock Diner at $156.00, 65 days past due (invoice 1024, due 3 June). Kookies by Kathy ($75.00) and Bill's Windsurf Shop ($85.00) are both around 45 days out.
Everything runs on your own machine. Nothing is hosted or deployed, and no company data leaves your computer except to Claude, in the answer.
The figures above are from one particular sandbox. You'll get your own sandbox company when you sign up, with its own company number, its own customers and its own dates — so your totals and overdue days will not match these. That's expected, not a fault. Every example in this README is illustrative for the same reason.
What you can ask
Question | Tool used |
Who owes us money? How overdue? Who should we chase? |
|
What bills do we owe? What's due soon? |
|
How profitable were we this year? What did we spend on X? |
|
What do we own and owe? How much cash? |
|
What's Amy's email? Who are our customers? |
|
Which company am I connected to? |
|
Anything else in the books |
|
The aging tools compute days overdue and bucket everything (current, 1–30, 31–60, 61–90, 90+) rather than making Claude do date arithmetic on raw invoices.
Related MCP server: qbo-mcp
What "read-only" means here
The server cannot write to QuickBooks. Not "writes are switched off" — there is no code that could write:
client.pyis the only module that can reach the QuickBooks API. It exposes a single request method, the HTTP verb is a hardcoded literal"GET", and every path is checked against an allowlist of exactly two prefixes (/queryand/reports/). QuickBooks writes arePOSTs to/v3/company/{realm}/{entity}, which is neither.tests/test_readonly.pyparses the source and fails the build if a non-GET verb appears in that module, if any other module grows its own HTTP client, or if the path allowlist changes.
The honest caveat: Intuit publishes no read-only scope for accounting data.
The OAuth token this server holds is capable of writing — the restriction lives
in this code, not in the token. If you don't trust the code, don't trust the
claim; read client.py (about 200 lines) and the test that guards it.
One POST does exist, in auth.py: the OAuth token exchange. It is pinned to
Intuit's token endpoint, which is a different host from the accounting API, and
the test asserts that too.
Want to see for yourself? Every request is logged. Open the MCP log
(%APPDATA%\Claude\logs\mcp-server-quickbooks.log) and you'll see only GET
lines.
Install
Takes about 10 minutes, most of it on Intuit's website.
If someone has handed you a Client ID, Client Secret, Realm ID and refresh token from an existing connection, skip steps 3 and 4 and run
uv run qbo-mcp-importinstead. Read When someone genuinely cannot make their own account first — it works, but you give up the ability to fix your own installation.
1. Install uv
uv runs the server and handles Python and dependencies for you.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Close and reopen your terminal afterwards. Check it worked:
uv --version(macOS or Linux: curl -LsSf https://astral.sh/uv/install.sh | sh)
2. Get this code
git clone https://github.com/CharlesPiccioneBTP/Local-MCP-server-for-QuickBooks-Sandbox.gitRemember where you put it — you'll need the full path in step 5.
3. Create your own Intuit app
Free, no card required. Do this yourself even if a colleague has already set theirs up — sandbox companies belong to the developer account that created them, so you can't connect to someone else's. You'll get your own, with its own sample data.
Sign up at developer.intuit.com. A sandbox company with realistic sample data is created for you automatically.
My Hub → Workspaces → + → Get Started → fill in the basic details.
+ to add an app → choose QuickBooks Online (Accounting) → name it anything (e.g. "Claude read-only").
Go to Settings → Redirect URIs → Development tab → Add URI and paste this exactly:
http://localhost:8000/callbackThis is the step people get wrong. It must be
http(nothttps), with no trailing slash. If it doesn't match character-for-character, Intuit refuses the sign-in and setup fails.Open Keys & credentials and keep the tab open. You need the Client ID and Client Secret from the Development section. (Sandbox and production have different keys — use Development.)
4. Connect your company
In a terminal, from the folder you cloned into:
uv run qbo-mcp-setupIt asks for the environment (press Enter for sandbox), then your Client ID and
Client Secret. Your browser opens; sign in and choose the sandbox company. The
secret isn't shown as you type and isn't saved to your shell history.
You should see:
Saved credentials to C:\Users\you\AppData\Local\qbo-mcp\credentials.json
Verifying the connection...
Success - connected to "Sandbox Company US 4768".5. Tell Claude Desktop about it
Open Claude Desktop → Settings → Developer → Edit Config. That opens
claude_desktop_config.json. Add the quickbooks block inside mcpServers:
{
"mcpServers": {
"quickbooks": {
"command": "uv",
"args": [
"--directory",
"C:\\Users\\you\\path\\to\\Local-MCP-server-for-QuickBooks-Sandbox",
"run",
"qbo-mcp"
]
}
}
}Two things to get right:
Replace the path with your folder from step 2. On Windows use double backslashes (
\\) as shown.If Claude Desktop reports it can't find
uv, replace"uv"with its full path. Find it by runningwhere uv(Windows) orwhich uv(Mac/Linux) — it's usuallyC:\Users\you\.local\bin\uv.exe.
No credentials go in this file — that's deliberate. This file gets shared and screenshotted when people ask for help. Your secrets live in the separate credentials file from step 4.
6. Restart Claude Desktop
Fully quit and reopen it — closing the window isn't enough. Then ask:
Who owes us money and how overdue is it?
Checking it works
uv run qbo-mcp-doctorThis runs without Claude and checks the whole chain. What matters is that every
line says ok — the company name and figures will be your sandbox's, not these:
[ ok ] Credentials loaded from C:\Users\you\AppData\Local\qbo-mcp\credentials.json
environment=sandbox realm=93414576XXXXXXXX
[ ok ] Token refresh succeeded
[ ok ] Refresh token unchanged this time (rotation is periodic); file is current
[ ok ] Refresh token expires in 101 days
[ ok ] Connected to "Sandbox Company US 4768"
[ ok ] Receivables aging: 20 open invoice(s), total outstanding 5281.52
current 3,756.02
1-30 1,128.50
31-60 241.00
61-90 156.00
90+ 0.00Run this first whenever something seems wrong — it separates "the server is broken" from "Claude Desktop isn't talking to it".
Troubleshooting
"No credentials found" — Setup hasn't been run, or it ran as a different
Windows user. Run uv run qbo-mcp-setup.
The QuickBooks tools don't appear in Claude Desktop — Almost always the
config file. Check the path uses double backslashes, then confirm the file is
valid JSON (a stray comma breaks it silently). Then fully quit and reopen the
app. If it still fails, check
%APPDATA%\Claude\logs\mcp-server-quickbooks.log.
"Port 8000 is already in use" during setup — Something else is using that port. Stop it and retry. The port must match the redirect URI registered with Intuit, so changing it means changing both.
Setup opens the browser but fails after sign-in — The redirect URI doesn't
match. It must be exactly http://localhost:8000/callback in Settings →
Redirect URIs → Development.
"Intuit rejected the client credentials (401)" — Wrong keys, or production keys used for a sandbox company. Copy them again from the Development section and re-run setup.
It worked for weeks, now it says "invalid_grant" — The connection needs
re-authorising. This happens if the token expires (see below), if it was revoked
in QuickBooks, or if two copies of the server fought over a refresh. Fix:
uv run qbo-mcp-setup.
Keeping it working
Access tokens last 1 hour and the server refreshes them automatically. The refresh token rotates roughly daily, and Intuit invalidates the old one immediately, so the new value is written to disk atomically, under a cross-process lock, before it's used. If two copies of the server start at once, the second adopts the first's tokens instead of refreshing again — which would otherwise disconnect both.
The refresh token itself is currently good for ~101 days from setup, and
that window resets every time it's used. So the server keeps working
indefinitely as long as it's used occasionally. If it goes unused for that long,
re-run uv run qbo-mcp-setup. The doctor warns you when fewer than 30 days
remain.
Where things live
Credentials |
|
Claude Desktop config |
|
Server logs |
|
Credentials are stored outside this repository so they cannot be committed by
accident. That's the actual protection — .gitignore is a backstop. Setup will
refuse outright to write them anywhere inside a git repository. The file is
locked to your user account (icacls on Windows, mode 600 elsewhere).
Rolling it out to colleagues
Send them this repository and point them at the install steps above. There is nothing to hand over besides the link — no keys, no config, no credentials file.
Each person follows the whole guide, including creating their own Intuit developer account. They get their own sandbox company, their own app, and their own Client ID and Secret, so there is nothing to share and nothing to keep secret between you. That is the intended setup, not a workaround.
Never copy a credentials.json between machines, even though it might look
like a shortcut. Two people sharing one credentials file will fight over the
refresh token — Intuit invalidates the old value each time it rotates, so
whoever refreshes second gets logged out, and eventually both do. Each person
needs their own OAuth grant.
When someone genuinely cannot make their own account
There is a second entry point for the case where a colleague must be got working without an Intuit account of their own — evaluating the tool before committing to accounts, or a non-technical user who should not be walked through a developer signup:
uv run qbo-mcp-importIt asks for the Client ID, Client Secret, Realm ID and refresh token of an
existing connection and writes the same credentials file qbo-mcp-setup writes.
No code path differs after that: the file format, the refresh logic and the
read-only guarantee are identical. The only thing skipped is the OAuth flow that
would have produced those four values.
Know what you are trading away before using it:
A refresh token works on one machine at a time. This is the same rotation problem as copying
credentials.json, because it is the same token. Whoever supplies it must stop using it. If both machines refresh, the second one is disconnected permanently.The recipient cannot repair their own installation. Every other failure in this README is fixed by re-running setup. They can't — that needs an account. Every outage becomes a request to whoever issued the token, and outages are guaranteed eventually: the refresh token expires after ~100 days of disuse.
Access tokens are not refresh tokens. The access token is the value people reach for, because it is the one that visibly works in
curl. It lasts an hour and cannot be renewed.importer.pydetects a pasted JWT or authorization code and says so, rather than failing opaquely three steps later.
For anyone who will use this for more than a trial, their own account remains the right answer. It takes about five minutes and removes every bullet above.
Tested end to end on Windows 11 only. The macOS and Linux credential paths
are covered by tests, so they resolve to the right place, but nobody has run the
real OAuth flow on those platforms yet. If a colleague is the first Mac user,
expect to iron something out — most likely the browser handoff during setup, or
file permissions on the credentials directory
(~/Library/Application Support/qbo-mcp/). Please report back if so.
Using it with a real company
This is built and tested against a sandbox. The code will work unchanged
against live books — answer production at the setup prompt and use Production
keys — but there is a real gate in front of you:
Intuit requires an app assessment before issuing production keys. Every app that touches production data must complete a legal, technical and security questionnaire and be approved by Intuit's security team. This applies whether or not the app is listed in the QuickBooks app store, and whether or not it is only ever used internally on your own company's books. Budget about an hour for the questionnaire, plus review time, and expect to supply your host domain, launch URL, disconnect URL, and the countries and IP addresses the app runs from — questions that assume a hosted web app and take some thought to answer for something that runs on a laptop.
Two other things worth deciding before you point this at real books:
Everything the tools return is sent to Claude in order to answer your question. Real customer names, balances and financial statements leave your machine. Whether that's acceptable is a policy call, not a technical one.
The read-only guarantee is unchanged — same code, same test — but the stakes of the honest caveat above go up. On real books, "the token could write, the code cannot" is worth someone else reading
client.pyto confirm.
For developers
uv run --group dev pytest # 101 tests, no network or credentials neededModule | Role |
| The only route to the QuickBooks API. GET-only, path-allowlisted. |
| OAuth setup and refresh. Holds the package's only POST. |
| Adopts a connection someone else authorised. No network of its own. |
| Credential storage: atomic writes, cross-process lock, git refusal. |
| QuickBooks operations, callable without an MCP session. |
| MCP tool definitions and descriptions. |
|
|
| Aging arithmetic, report flattening. |
| Static entity reference for |
Notes on design decisions worth knowing before changing things:
Tools raise plain exceptions, never
MCPError. In this SDK a plain exception becomes a tool error whose message the model reads and can act on;MCPErrorbecomes a protocol error the model never sees. Every failure here is one the user needs told about.AR aging is computed from
Invoicerows, not Intuit's aging report. Invoice rows already embedCustomerRef.name, so no join is needed, and it keeps the bucket boundaries under our control. Their Reports API is used for the financial statements, where the aggregation genuinely has to come from QuickBooks.describe_schemais a tool, not an MCP resource, even though resources fit static reference data better. Claude Desktop requires resources to be attached by hand, so it would never be read — andrun_querywithout it is guesswork.The QuickBooks query language is not SQL. No
JOIN,GROUP BY,OR,HAVING, or!=.qbo_sql.pycatches these and explains the workaround rather than passing them through to an opaque Intuit 400.minorversionis pinned (currently 75). Intuit changes response shapes between minor versions; an unattended server shouldn't have its output shift underneath it.
License
MIT — see LICENSE.
Available Tools
8 toolsdescribe_schemaA
Which QuickBooks entities and fields can be queried, and the dialect rules.
Call this before writing a run_query statement. With no argument it lists every queryable entity and available report; with an entity name it returns that entity's key fields. Costs no API call.
Args: entity: Entity name such as "Invoice" or "Customer". Omit for the overview.
Inputs: entity. Returns: object
find_contactsA
Look up customers or vendors, with contact details and balances.
Use to find someone by partial name, to list who the business deals with, or to get an email or phone number. The balance returned is that contact's total outstanding; for invoice-level detail and overdue days use get_receivables_aging.
Args: name_contains: Case-insensitive partial name. Omit to list everyone. kind: "customer" or "vendor". include_inactive: Include archived records. Defaults to active only. limit: Maximum records to return (capped at 500).
Inputs: kind, limit, name_contains, include_inactive. Returns: object
get_balance_sheetA
Assets, liabilities and equity at a point in time.
Use for questions about what the business owns and owes overall, cash position, or financial standing. For "who owes us money" specifically, get_receivables_aging gives a far more useful breakdown than the single receivables line on this report.
Args: as_of: Balance sheet date, YYYY-MM-DD. Defaults to today. accounting_method: "Accrual" or "Cash". Defaults to the company setting.
Inputs: as_of, accounting_method. Returns: object
get_company_infoA
Name, address and fiscal year of the connected QuickBooks company.
Useful for confirming which company the answers refer to, and for finding the fiscal year start before asking for period reports.
Inputs: no named parameters. Returns: object
get_payables_agingA
Who the business owes money to, and how overdue each bill is.
The accounts-payable mirror of get_receivables_aging: use it for unpaid bills, money owed to suppliers or vendors, and upcoming payment obligations. Same shape of answer, aged into the same buckets.
Args: as_of: Date to age against as YYYY-MM-DD. Defaults to today. min_days_overdue: Only include bills at least this many days late. vendor: Case-insensitive substring to limit results to one vendor.
Inputs: as_of, vendor, min_days_overdue. Returns: object
get_profit_and_lossA
Income, expenses and net profit over a period.
Use for questions about revenue, sales totals, expenses, spending, margins or whether the business is profitable. Defaults to the current fiscal year to date when no dates are given.
Args: start_date: Period start, YYYY-MM-DD. end_date: Period end, YYYY-MM-DD. accounting_method: "Accrual" or "Cash". Defaults to the company setting.
Inputs: end_date, start_date, accounting_method. Returns: object
get_receivables_agingA
Who owes the business money, and how overdue each amount is.
Use this for any question about unpaid customer invoices, accounts receivable, overdue accounts, collections, or who is behind on payment. Returns every open invoice with the customer name, due date, days overdue and outstanding balance; per-customer totals ranked worst-first; and totals per aging bucket (current, 1-30, 31-60, 61-90, 90+ days).
Args: as_of: Date to age against as YYYY-MM-DD. Defaults to today. min_days_overdue: Only include invoices at least this many days late. 0 (the default) includes invoices that are not yet due. customer: Case-insensitive substring to limit results to one customer.
Inputs: as_of, customer, min_days_overdue. Returns: object
run_queryA
Run a read-only QuickBooks query for anything the other tools miss.
Only SELECT statements are accepted, and this server can only issue read requests, so no query can modify data. The language is a restricted subset of SQL: no JOIN, GROUP BY, OR, or aggregate functions. Call describe_schema first to check entity and field names, and prefer the purpose-built tools where one fits -- they do arithmetic this cannot.
Example: SELECT * FROM Invoice WHERE TxnDate >= '2026-01-01'
Args: query: A QuickBooks SELECT statement.
Inputs: query (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct domain area: receivables, payables, profit/loss, balance sheet, company info, contacts, querying, and schema discovery. Even the two aging tools are clear mirrors for AR vs AP. No overlap or ambiguity.
Most tools follow a consistent get_<noun> pattern, with find_contacts as a slight deviation and run_query/describe_schema as verb_noun. All are lowercase snake_case, so the pattern is predictable and readable.
8 tools is well-scoped for a read-only QuickBooks reporting server. Each tool has a distinct purpose, and the count is neither too thin nor overwhelming.
The server covers core financial statements, aging reports, contact lookup, company info, and a flexible query tool with schema discovery. This provides comprehensive coverage for typical accounting questions, with run_query bridging any remaining gaps.
Maintenance
Related MCP Connectors
The best QuickBooks Desktop MCP server on the planet: every operation on every record type
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA secure, local-first MCP server that enables users to query QuickBooks data such as accounts, bills, and customers using natural language within Claude Desktop. It provides a direct interface to the QuickBooks API for streamlined financial data retrieval and management.10-
- AlicenseAqualityDmaintenanceMCP server for QuickBooks Online providing read-only access to customers, vendors, invoices, bills, and chart of accounts. Enables natural language queries to your financial data through Claude or any MCP client.8MIT
- AlicenseNot gradedqualityDmaintenanceA local MCP server that exposes QuickBooks Online data and actions as callable tools for AI assistants.MIT
- AlicenseNot gradedqualityCmaintenanceA local MCP server that exposes QuickBooks Online data and actions as callable tools for AI assistants, supporting entities like customers, invoices, bills, and financial reports.4MIT