Enables AI agents to apply changes to QuickBooks Online transactions, including reclassifying accounts, updating classes/locations, changing customers/vendors, and editing memos, either via CSV file or direct tool calls.
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., "@qbo-mcp reclassify the last office supplies expense to Computer Equipment"
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.
Apply CSV-driven changes to QuickBooks Online transactions, plus an MCP server
(qbo-mcp) that exposes the same operations to Claude / any MCP client.
Company-agnostic: one install can drive multiple QBO companies via profiles (see Multiple companies).
Workflow: export a Transaction Detail report from QBO, edit a copy of the CSV (or build one from scratch) with the changes you want, then run the applier. Or skip the CSV and drive edits conversationally via the MCP server.
Edit existing posted transactions:
Account reclassification (line item)
Class / Location
Customer / Vendor (entity ref)
Memo / Description
Out of scope: mapping pending bank-feed "For Review" items.
Related MCP server: QuickBooks Online MCP Server
Intuit's Production OAuth keys require an HTTPS redirect URI. They reject
http://localhost... for production. To avoid making every user run a tunnel
(ngrok etc.), this repo ships a static bouncer page at docs/index.html
that you publish on GitHub Pages.
Push this repo to your own GitHub account (e.g. <you>/qbo-mcp).
In the repo on GitHub: Settings → Pages.
Under Source, choose Deploy from a branch, select main and /docs.
Save. After ~30 seconds, your bouncer URL is https://<you>.github.io/qbo-mcp/.
The page is a stateless redirect — it just reads ?code=...&state=...&realmId=...
from the URL and forwards them to http://localhost:<port>/callback on your
machine. The port is encoded in the OAuth state param so multiple machines —
and multiple companies — can share the same bouncer URL.
You need one Intuit Developer app per QBO company (Intuit ties client credentials to the app, and you authorize each company separately).
Sign in at https://developer.intuit.com with your Intuit ID.
Dashboard → Create an app → choose QuickBooks Online and Payments.
Name it (e.g. qbo-mcp-natu). Scope: com.intuit.quickbooks.accounting.
Under Keys & credentials, switch to the Production tab.
Add redirect URI: https://<you>.github.io/qbo-mcp/ (from step 1, with trailing slash).
Copy the Client ID and Client Secret into your .env (or .env.<profile>).
Set QBO_REDIRECT_URI=https://<you>.github.io/qbo-mcp/.
Sandbox shortcut: To try the flow against QBO's sandbox first, switch to the Development tab in step 4, register
http://localhost:8765/callbackas the redirect URI, setQBO_ENV=sandbox, and skip step 1 entirely.
Note: Production keys for a self-distributed app you only connect to your own QBO company do not require Intuit's app review.
python3 -m venv ~/.venvs/qbo-mcp
source ~/.venvs/qbo-mcp/bin/activate
pip install git+https://github.com/<you>/qbo-mcp.git # or: pip install -e . from a cloneThis installs four console scripts: qbo-auth, qbo-apply, qbo-find, qbo-mcp.
Either export them in your shell, or drop a .env file in the directory you run
the commands from (python-dotenv reads from cwd):
export QBO_CLIENT_ID=...
export QBO_CLIENT_SECRET=...
export QBO_REDIRECT_URI=https://<you>.github.io/qbo-mcp/qbo-authThis opens a browser, you log into QBO and pick the company, and tokens are
written to ~/.config/qbo-mcp/<profile>/tokens.json (override with
QBO_TOKENS_PATH). Refresh tokens last 100 days; access tokens auto-refresh.
One install can serve several QBO companies. Set QBO_PROFILE to a short
company slug; it namespaces tokens (~/.config/qbo-mcp/<profile>/tokens.json)
and selects a per-company env file.
Keep base settings in .env, and company-specific credentials in .env.<profile>
(these override the base .env whenever QBO_PROFILE is set):
.env # shared, e.g. QBO_REDIRECT_URI, QBO_ENV
.env.natu # QBO_CLIENT_ID / QBO_CLIENT_SECRET for the Natu Intuit app
.env.span # QBO_CLIENT_ID / QBO_CLIENT_SECRET for the Span Intuit appAuthorize each company once:
QBO_PROFILE=natu qbo-auth
QBO_PROFILE=span qbo-authThen every command targets a company via the same env var:
QBO_PROFILE=span qbo-find Bill --vendor "AWS" --date 2026-04-15
QBO_PROFILE=span qbo-apply changes.csv --dry-runWith QBO_PROFILE unset, everything uses the default profile — fine for a
single-company setup.
Set QBO_READONLY=1 (typically in a profile's .env.<profile>) to block all
writes — update_transaction, apply_csv, and qbo-apply refuse at the client
layer, while reads/queries keep working. Use it for companies you only want to
inspect. There is no read-only QBO OAuth scope, so this guard (not Intuit) is what
enforces it; unset the var to re-enable writes.
qbo-apply path/to/changes.csv --dry-run
qbo-apply path/to/changes.csvCSV columns: txn_type, txn_id, line_id, field, new_value
txn_type: QBO entity name — JournalEntry, Bill, Invoice, Purchase (= cash/check/CC expense), Deposit
txn_id: QBO internal Id (not the displayed Doc Number — see below)
line_id: required for line-level edits (account, class on a line, line memo). Empty for header-level edits (vendor on a Bill, location on most txns, txn-level memo)
field: account | class | location | customer | vendor | memo
new_value: name of the target Account/Class/Department/Customer/Vendor, or memo text
See changes_example.csv.
The displayed reference (e.g. JE-1042) is not the API Id. Use the helper:
qbo-find JournalEntry --doc-number JE-1042
qbo-find Bill --vendor "Amazon Web Services" --date 2026-04-15
qbo-find Invoice --customer "Acme Corp" --date-range 2026-04-01 2026-04-30
qbo-find Purchase --amount 1234.56Or open the transaction in QBO — the URL contains txnId=<id>.
Item-based lines (Invoice line items, item-based Bill lines) get their account from the Item — change the Item, not the line account.
All edits to one transaction are batched into a single sparse update (all-or-nothing per txn).
tokens.json lives at ~/.config/qbo-mcp/<profile>/tokens.json (override via QBO_TOKENS_PATH); refresh tokens last 100 days.
qbo-mcp)The same operations are exposed as an MCP server so an MCP client (e.g. Claude Desktop, Claude Code) can drive QBO edits in chat without writing a CSV.
qbo-mcp # stdio transportFor multiple companies, register one server entry per profile — each with
its own QBO_PROFILE and credentials. The server name reports the profile
(qbo-mcp (span)), so Claude can tell them apart.
Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"qbo-natu": {
"command": "/Users/<you>/.venvs/qbo-mcp/bin/qbo-mcp",
"env": {
"QBO_PROFILE": "natu",
"QBO_CLIENT_ID": "...",
"QBO_CLIENT_SECRET": "...",
"QBO_REDIRECT_URI": "https://<you>.github.io/qbo-mcp/"
}
},
"qbo-span": {
"command": "/Users/<you>/.venvs/qbo-mcp/bin/qbo-mcp",
"env": {
"QBO_PROFILE": "span",
"QBO_CLIENT_ID": "...",
"QBO_CLIENT_SECRET": "...",
"QBO_REDIRECT_URI": "https://<you>.github.io/qbo-mcp/"
}
}
}
}Claude Code: claude mcp add qbo-span --scope user --env QBO_PROFILE=span --env QBO_CLIENT_ID=... --env QBO_CLIENT_SECRET=... -- /Users/<you>/.venvs/qbo-mcp/bin/qbo-mcp
Tools exposed:
find_transactions — search by doc number, date, customer/vendor, amount
get_transaction — fetch a full entity (use to read line Ids before editing)
lookup_ref — resolve an Account/Class/Department/Customer/Vendor name to its Id
query — read-only QBO SQL passthrough
update_transaction — apply granular field changes to one transaction (defaults to dry_run=True)
apply_csv — batch path, same CSV format as qbo-apply (defaults to dry_run=True)
Both write tools default to dry_run=True. To commit, pass dry_run=False
explicitly — Claude will surface the change plan first either way.
OAuth still happens via qbo-auth (one-time per company); the MCP server reads
tokens.json and refreshes access tokens automatically.
Apply a CSV of changes (columns: txn_type,txn_id,line_id,field,new_value) in batch.
Mirrors qbo-apply. dry_run=True (default) resolves refs and reports the plan;
dry_run=False commits. Returns per-transaction results plus an ok/fail tally.
| Name | Required | Description | Default |
|---|---|---|---|
| csv_path | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers the key behavioral modes (dry_run vs commit) and mentions return format (per-transaction results plus tally). However, it does not disclose potential destructive actions from commiting, error handling, or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at four sentences, front-loaded with the main action, and every sentence adds necessary information about columns, behavior, and output. Could be slightly more structured but efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and low schema coverage, the description explains the tool's core functionality and return format adequately. However, it lacks details on error handling, CSV validation, or impact on existing data, which would be helpful for a batch update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must add meaning. It explains the dry_run parameter's default and effect (resolves refs/plans vs commits), but does not describe the csv_path parameter format or constraints beyond listing column names. Partial value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies a CSV of changes in batch, specifying the column structure. It references 'qbo-apply' which helps contextualize, though it's not a direct sibling. The verb 'Apply' and resource 'CSV of changes' is specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Mirrors qbo-apply' but does not explain when to use this tool versus the listed siblings like update_transaction or query. No explicit when-to-use or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search QBO transactions by metadata, returning Id + key fields per match.
txn_type: one of Bill, Invoice, JournalEntry, Purchase, Deposit, CreditMemo, VendorCredit. Provide at least one filter. date_start/date_end define a TxnDate range (YYYY-MM-DD). customer is for Invoice/CreditMemo; vendor is for Bill/Purchase/VendorCredit.
| Name | Required | Description | Default |
|---|---|---|---|
| txn_type | Yes | ||
| doc_number | No | ||
| date | No | ||
| date_start | No | ||
| date_end | No | ||
| customer | No | ||
| vendor | No | ||
| amount | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions returning Id and key fields, but does not disclose pagination behavior, rate limits, or whether the operation is read-only (though implied). The limit parameter is not explained in the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no redundancy. It starts with the core purpose, then lists txn_type values, and finally explains date range and entity filters. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no output schema, and no annotations, the description is somewhat incomplete. It does not explain the output structure beyond 'Id + key fields', nor does it clarify the behavior of the limit parameter or single date parameter. The description is adequate but not fully comprehensive for a parameter-rich search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It covers txn_type, date_start/date_end, customer, and vendor, but not doc_number, date, amount, or limit. The description adds some meaning beyond the schema (e.g., txn_type list, customer/vendor mapping), but incomplete parameter documentation reduces effectiveness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches QBO transactions by metadata and returns Id plus key fields. This differentiates from siblings like get_transaction (single transaction retrieval) and update_transaction (modification). The verb 'Search' and resource 'transactions' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that txn_type must be one of the listed types, and provides guidance on using customer vs vendor filters. It states 'provide at least one filter', implying when to use additional parameters. However, it does not explicitly mention when not to use this tool compared to alternatives like get_transaction or query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full QBO entity for a transaction. Use to inspect Line[].Id and current values.
| Name | Required | Description | Default |
|---|---|---|---|
| txn_type | Yes | ||
| txn_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behaviors. It states 'Fetch the full QBO entity', implying a read-only operation. However, it does not mention side effects, permissions, rate limits, or what 'full entity' entails beyond the hint. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. The first sentence states purpose, the second adds a specific use case. Could be considered slightly under-specified but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and zero parameter documentation, the description is incomplete. It does not explain return format, errors, or the scope of 'full QBO entity'. For a fetch tool, more context (e.g., what the return includes, pagination if any) is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and the description adds no meaning to parameters 'txn_type' and 'txn_id'. It does not explain valid values, formats, or how to use them. This is a critical gap for parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches the full QBO entity for a transaction, specifying a distinct resource. Mention of inspecting Line[].Id adds specific use context. However, it does not explicitly differentiate from siblings like find_transactions or query, which could also retrieve transaction data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage hint ('Use to inspect Line[].Id and current values') but lacks explicit guidance on when to use this tool versus alternative siblings. No exclusions or prerequisites are mentioned, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a list-entity name to its QBO Id. entity_type: Account, Class, Department, Customer, Vendor.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_type | Yes | ||
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the function. Does not disclose read-only nature, authentication requirements, or error behavior. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence plus a list of entity types. No unnecessary words or structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup with 2 params and no output schema, the description is adequate but leaves gaps: return format, uniqueness, error handling not mentioned. Could benefit from specifying output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds value by listing valid entity_type values (Account, Class, Department, Customer, Vendor). However, no constraints or details for the 'name' parameter are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves a list-entity name to its QBO Id, specifies the entity types (Account, Class, Department, Customer, Vendor), and is distinct from sibling tools which involve CSV import, transaction queries/updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings like 'query' or 'find_transactions'. Lacks prerequisites, alternatives, or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a read-only QBO SQL query (e.g. SELECT * FROM Class). Returns raw entity rows.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. States 'read-only' and 'returns raw entity rows,' but omits details like error handling, rate limits, or SQL constraints beyond the example.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action, example, and return type. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values need not be described. Simple tool with one param; description covers purpose, example, and nature. Minor gaps in error handling or security.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single 'sql' parameter with 0% schema coverage. Description adds value with QuickBooks context and an example query format, though could explicitly restrict to SELECT statements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool runs a read-only QBO SQL query with an example (SELECT * FROM Class) and mentions returns raw entity rows. Distinguishes from sibling tools by emphasizing read-only nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings like find_transactions or lookup_ref. The read-only hint is implicit but lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply one or more field changes to a single transaction.
Each change is {"line_id": "", "field": "account|class|location|customer|vendor|memo", "new_value": "..."}. Omit line_id (or pass null) for header-level fields. dry_run=True (default) resolves refs and reports the plan without writing; pass dry_run=False to commit the sparse update.
| Name | Required | Description | Default |
|---|---|---|---|
| txn_type | Yes | ||
| txn_id | Yes | ||
| changes | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that dry_run defaults to True, resolving references and reporting a plan without writing, and that passing dry_run=False commits the update. This is a key behavioral trait. It does not mention side effects or error handling, but covers the essential operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: three sentences that front-load the purpose, then detail the change format and dry_run flag. Every sentence adds necessary information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should clarify what the tool returns (plan on dry_run, confirmation or error on commit). It mentions 'reports the plan' but does not specify the response format. Also, it lacks context on permissions or error scenarios. While core usage is covered, completeness is slightly lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds detailed meaning for the 'changes' parameter (structure and fields) and 'dry_run' behavior. The 'txn_type' and 'txn_id' are not elaborated, but their purpose is clear from context. Overall, it adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it applies one or more field changes to a single transaction. The verb 'Apply' and resource 'transaction' are specific. It distinguishes from siblings like get_transaction (read) and find_transactions (search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the tool (change format, dry_run flag) but does not provide context on when to choose this tool over siblings. No explicit when/when-not or alternatives are mentioned, though the dry_run feature is well-explained for safe usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0apply_csvfind_transactionsget_transactionlookup_refqueryupdate_transactionScored across 6 tools
Each tool has a clearly distinct purpose: batch updates vs single updates, searching vs full fetch vs SQL query, and name resolution. No two tools overlap in functionality.
Most tools follow a verb_noun pattern (apply_csv, find_transactions, get_transaction, update_transaction), but 'lookup_ref' uses a verb+noun and 'query' is a single noun, breaking the pattern slightly. Overall consistent snake_case.
6 tools is well-scoped for a QuickBooks Online MCP, covering search, retrieval, updates (single and batch), reference resolution, and raw queries without being excessive.
The tool set lacks a create transaction tool, which is a notable gap for typical CRUD operations. While read and update are covered, agents cannot create new transactions, limiting the server's usefulness.
MCP server for Modern Treasury — payment orders, transactions, counterparties and ledgers.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Hosted MCP server for Mini Accountant: invoices, expenses, customers, analytics, tax estimates.
MCP server for Codat — companies, connections, invoices, bills and financial statements.
