TenkeyBridge
← Back to blog

A QuickBooks MCP Server for Desktop: Giving an AI Agent Safe, Checkable Access

  • quickbooks mcp server
  • ai agent quickbooks desktop
  • claude quickbooks integration
Developer seen from behind editing an MCP server JSON config on a laptop beside a chat window at night

Quick answers

What is the TenkeyBridge MCP server? @tenkeybridge/mcp is an npx-ready stdio MCP server that exposes a QuickBooks Desktop or Enterprise company file to an MCP client like Claude Desktop through a QuickBooks Online–shaped REST API.

What tools does it expose? Five: query, get, create, update, delete — plus a compat://catalog resource and compat://entity/{name} so the agent can check support before it calls.

Can an AI agent write to QuickBooks Desktop? Yes, and that's the risk: on a real realm, a create or update posts a real transaction to real books. Develop against the sandbox first.

How does the agent avoid guessing at fields? It reads the compatibility resources, and when it still gets it wrong, faults come back with status, code, human-readable fixes, and a docsUrl it can follow.

Do I need the MCP server to write code? No — @tenkeybridge/client is the typed TypeScript client for deterministic application code. MCP is for agents and exploration.

The actual problem with agents and accounting data

Model Context Protocol solved the plumbing question. An MCP client can discover tools, call them, and read resources without you writing a bespoke function-calling shim per model. What MCP does not solve is the thing that makes accounting integrations hard: the model doesn't know what your backend supports, and it will cheerfully hallucinate a field name that the QuickBooks Online API documents but QuickBooks Desktop has never heard of.

If you've shipped against QBO, you already know the shape of this. Invoice has CustomerMemo, TxnTaxDetail, LinkedTxn, GlobalTaxCalculation. Some of those map cleanly onto qbXML. Some don't exist on Desktop at all. An agent with a generic HTTP tool and a copy of the QBO docs in its context window will produce requests that are 90% right and fail in ways it can't reason about — a bare 400 with a vendor string is not something a model can self-correct from.

So the design question for a QuickBooks MCP server isn't "which HTTP calls do I wrap." It's: what does the agent need to read before it writes, and what does it need to get back when it's wrong?

Five tools, not fifty

@tenkeybridge/mcp exposes five tools that map to the REST verbs you already use:

  • query — run a QBO-style SQL-ish query (SELECT * FROM Invoice WHERE TxnDate > '2024-01-01')
  • get — fetch one entity by Id
  • create — create an entity
  • update — update an entity (sparse or full)
  • delete — delete/void where the entity supports it

That's deliberate. The alternative design — one tool per entity, so create_invoice, create_customer, update_vendor and so on — blows up the tool list to a hundred-plus entries, eats context, and makes tool selection noticeably worse. Five generic tools with an entity parameter keeps the surface small and lets the model spend its attention on the payload, which is where the actual difficulty lives.

The trade-off is honest: generic tools mean the schema can't fully describe what a valid Invoice body looks like. That's what the compatibility resources are for.

The compatibility catalog is the point

Two MCP resources ship alongside the tools:

  • compat://catalog — the full list of entities, with supported operations per entity
  • compat://entity/{name} — per-entity detail: which fields are supported, which are read-only, which are ignored on Desktop, which are unsupported outright

A well-prompted agent reads compat://entity/Invoice before it builds an invoice body. In practice, that turns a class of silent failures into a check the model can do for itself. When it asks "can I set GlobalTaxCalculation on a Desktop invoice," there is an authoritative answer in the session instead of a guess.

This is the same data as the public Desktop parity matrix, served in a form a model can read mid-conversation. It's worth skimming yourself before you wire anything up — the gaps are real and it's better to know which ones matter to your workflow before an agent discovers them on your behalf.

A reasonable system prompt for an agent using this server:

Before creating or updating any entity, read compat://entity/{EntityName} and only use fields listed as supported. If a fault returns a fixes array, apply the suggested fix and retry once. Never retry a create that returned a 5xx without first running a query to check whether the entity was created.

That last line matters more than it looks. Retry-after-timeout on a create is how you get duplicate invoices, with an agent or without one.

Faults an agent can actually act on

TenkeyBridge maps Desktop's native error vocabulary — qbXML status codes, COM HRESULTs, the occasional opaque "QuickBooks found an error" — into QBO-style faults, with extra fields aimed squarely at machine consumers:

{
  "Fault": {
    "Error": [{
      "Message": "Invalid Reference Id",
      "Detail": "Customer with Id '1042' not found in this company file.",
      "code": "610",
      "fixes": [
        "Query Customer to confirm the Id exists",
        "Customers deleted in QuickBooks Desktop are not returned by query"
      ],
      "docsUrl": "https://docs.tenkeybridge.com/compatibility/"
    }],
    "type": "ValidationFault"
  },
  "status": 400
}

The fixes array and docsUrl exist because a model's recovery behavior is only as good as the signal it gets. Give it "error -2147220472" and it will apologize and try the same request again. Give it "this Id doesn't exist, here's how to check," and it runs a query and gets it right on the second attempt. If you want the full mapping story — which Desktop conditions become which HTTP status — we wrote that up in Decoding QuickBooks Desktop Errors.

Wiring it up

The server runs over stdio via npx, so there's nothing to install globally. Claude Desktop, Cursor, Continue, and anything else that speaks MCP take the same config shape:

{
  "mcpServers": {
    "tenkeybridge": {
      "command": "npx",
      "args": ["-y", "@tenkeybridge/mcp"],
      "env": {
        "TENKEYBRIDGE_CLIENT_ID": "<your-client-id>",
        "TENKEYBRIDGE_CLIENT_SECRET": "<your-client-secret>",
        "TENKEYBRIDGE_REFRESH_TOKEN": "<your-refresh-token>",
        "TENKEYBRIDGE_REALM_ID": "<your-realm-id>",
        "TENKEYBRIDGE_BASE_URL": "https://api.tenkeybridge.com"
      }
    }
  }
}

Three notes on credentials, because this config file is going to sit in plaintext in your home directory:

  1. Use a dedicated OAuth2 client for agent work. Don't share the client your production sync uses. If you need to revoke in a hurry, you want to revoke one thing.
  2. Refresh tokens rotate. The server exchanges the refresh token for an access token on startup and refreshes as needed. When a rotated refresh token supersedes the one in your config, the value on disk goes stale — if the server starts failing auth after an idle period, re-issue and paste a fresh one. Treat the config value as a bootstrap credential, not a permanent secret.
  3. Point it at the sandbox realm first. See below.

Full walkthrough including the OAuth2 dance is in the AI quickstart.

Develop against the sandbox, not your books

The free sandbox serves a pre-populated ExampleCo company file over the same API host, with the same auth, the same entity shapes, and the same faults. Pat Owner is in there as a customer. There are invoices, items, vendors, and a chart of accounts to query against.

Use it for the entire iteration loop: prompt engineering, tool-selection debugging, figuring out which compat resources your agent actually reads unprompted. The sandbox has no QuickBooks installation behind it and nothing you do there touches a real file — which also means it's the right place to let an agent fail loudly. If you want a side-by-side of how sandbox requests compare to what you're used to from Intuit's, we covered that in QBO Sandbox vs. TenkeyBridge Sandbox.

When you do switch to a production realm, switch deliberately and know what changes.

Be honest about what "safe" means

The word "safe" in the title of this post is doing limited work, and it should. Here is the accurate version:

Writes are real. There is no dry-run mode, no staging layer, no undo. A create against a production realm posts a real transaction to a real company file. An update with a full-replacement body clobbers fields the agent didn't include — which is a specific failure mode worth understanding independently of agents, and we went deep on it in Sparse Updates vs. Full Replacement. Agents are, in our experience, somewhat more likely than human-written code to send a full body when they meant to send a sparse one.

The model chooses the tool calls. MCP doesn't give you per-tool authorization. If you want the agent read-only, you have two real options: approve each tool call manually in a client that supports it, or run against credentials that can't write. Hope is not an access control strategy.

Nothing here is an audit trail. Transactions an agent creates show up in QuickBooks attributed to the integration's credentials, same as any API write. If you need to distinguish agent-originated changes from human ones for a reviewer, put that in a memo or a custom field yourself.

Desktop parity is incomplete. Some QBO entities have no Desktop equivalent; some fields are ignored or read-only. The catalog resource tells the agent this, but only if the agent reads it. A model under pressure to finish a task will sometimes skip the check.

Reasonable defaults, if you're deciding where to land:

  • Read-only agents against production: fine, genuinely useful, low blast radius.
  • Writing agents against production: only with human approval in the loop on create/update/delete, or scoped to one entity type you've tested hard.
  • Fully autonomous writing agents: sandbox only, until you've built your own guardrails above the MCP layer.

When you want code instead of an agent

MCP is for exploration, ad-hoc analysis, and workflows where a human is reading the output. For the scheduled sync that runs at 2am with nobody watching, you want deterministic code, and for that there's @tenkeybridge/client — a typed TypeScript client over the same REST API:

import { TenkeyBridge } from "@tenkeybridge/client";

const qb = new TenkeyBridge({
  clientId: process.env.TKB_CLIENT_ID!,
  clientSecret: process.env.TKB_CLIENT_SECRET!,
  refreshToken: process.env.TKB_REFRESH_TOKEN!,
  realmId: process.env.TKB_REALM_ID!,
});

const { QueryResponse } = await qb.query(
  "SELECT * FROM Invoice WHERE Balance > '0' MAXRESULTS 50"
);

Same auth, same entities, same faults — autocomplete instead of prompt engineering. Plenty of teams run both: the client in the sync job, MCP on a developer's laptop for poking at a customer's file while debugging. Details in the npm client guide.

If your integration already runs against QuickBooks Online and you're sizing up the Desktop side more broadly, the swap checklist is the better starting point — MCP is a layer on top of that, not a substitute for it.

FAQ

What exactly does the MCP server expose to the model?

Five tools (query, get, create, update, delete) and two resources (compat://catalog, compat://entity/{name}). Tool arguments take an entity name and a body, which is why the compatibility resources matter — they're how the model learns what a valid body looks like for a given entity on Desktop.

How does the agent know which fields QuickBooks Desktop supports?

By reading compat://entity/{name} before it builds a payload, which lists supported, read-only, ignored, and unsupported fields for that entity. Most MCP clients won't fetch a resource unprompted, so put the instruction in your system prompt. The same information is browsable at the compatibility docs if you want to check it yourself first.

Is it safe to let an agent write to QuickBooks?

On a production realm, treat it the way you'd treat giving a new contractor write access on day one — fine with review, risky without. Use manual tool-call approval, scope the credentials, and do all iteration on the sandbox. There's no dry-run mode and no undo.

Does this work with anything other than Claude?

Yes. It's a standard stdio MCP server, so any MCP-capable client — Cursor, Continue, VS Code's agent mode, your own client built on the MCP SDK — takes the same mcpServers config. Claude Desktop is just the most common first stop for a Claude QuickBooks integration.

Does the agent need QuickBooks Desktop running on the same machine?

No. The MCP server talks HTTPS to the TenkeyBridge API; the connection to the company file is handled separately, including for hosted environments. If your customers run on Rightworks or another hosted provider, this post covers how that side works.

Can I limit the agent to read-only?

Not through MCP itself — the protocol has no per-tool permission model. Use a client that prompts for approval on each tool call, or provision credentials whose scope can't write. Don't rely on prompt instructions alone to keep a model from calling delete. Config, credentials, and a working ExampleCo file to point it at: docs.tenkeybridge.com/guide/ai-quickstart — or just grab sandbox keys at try.tenkeybridge.com and see what your agent does with them.