Skip to main content
Conductor’s MCP server at https://mcp.conductor.is/ gives an AI agent the full Conductor API for QuickBooks Desktop: every operation in this API reference, for every record type and report. It accepts a sign-in through the Conductor Dashboard (OAuth) or a Conductor secret key as a Bearer token, and reaches the company files connected to the key’s project. This page is for developers building an agent on the MCP and for AI agents learning how it works; to connect Claude, ChatGPT, or another AI tool, follow the MCP guide.

Addresses

The root address, https://mcp.conductor.is/, is the one the guide’s setup steps use (Copilot Studio reaches it at /mcp), and it reaches every Conductor API operation: the QuickBooks tools cover common tasks, the general tools cover every record type, report, and field, and execute runs code for multi-step jobs and anything else. Its read-only address, https://mcp.conductor.is/read-only, gives the AI tool the read tools and execute, and the server refuses a write tool before anything reaches QuickBooks. On a read-only connection, the code runner refuses execute code that names one of the SDK’s write methods, which guards against the AI tool making a change by accident; it isn’t a security boundary, as Code execution explains. The Claude and ChatGPT directory listings connect to their own addresses on the same server: https://mcp.conductor.is/claude has the QuickBooks tools plus the general read, create, and update tools, and https://mcp.conductor.is/chatgpt has the QuickBooks tools.

Tools

The root address has the tools below. Every tool except execute makes at most one Conductor API request per call, and read tools never change anything. On the root address, delete_transaction and void_transaction remove or void a transaction; the Claude and ChatGPT directory listings don’t offer them.

Company files

Reports

Customers, vendors, accounts, and classes

Items

Transactions

Write tools

General tools

The general tools take the record type as resource, or a report category as reportCategory; see Any other record type. The first four read, and the last four make changes.

Running code

Any other record type

The QuickBooks tools cover the record types most people use, and each takes the fields used most often. The general tools reach every record type, report, and field the Conductor API has: the types without a QuickBooks tool, such as employees, transfers, sales tax codes, time tracking, and payroll reports, and the fields a QuickBooks tool leaves out, such as an invoice’s shipping address. They take the record type as resource, spelled as in the API reference and the SDKs (salesTaxCodes, timeTrackingActivities, billsToPay), or a report category as reportCategory, and their other inputs use the API’s own field names, which the API validates.
  • describe_operation shows what a call needs. For a record type and an operation (a report is reports/<category> with the operation report), it returns each field with a one-sentence description, the required fields, the HTTP method and path, and the SDK method to use in execute. It doesn’t contact QuickBooks.
  • list_records takes the type’s list filters, get_record an id (company and preferences take none), create_record and update_record the request body, and run_report a report category, including the five categories without a QuickBooks tool: budgetSummary, job, time, payrollDetail, and payrollSummary.
  • An unknown field fails with INVALID_ARGUMENTS and the list of valid fields, so the AI tool can correct the call.
  • list_records returns at most 150 records per call, with hasMore and remainingCount and no cursor, because a QuickBooks cursor stops working 20 seconds after the previous page, usually before an AI tool’s next turn. The AI tool narrows the dates or filters to reach the rest, or pages through the whole list in one execute call.
  • delete_transaction removes a transaction, and QuickBooks keeps no record of it; void_transaction keeps it with every amount set to zero. Only transactions can be deleted or voided. Customers, vendors, items, and accounts are made inactive instead, by setting isActive to false with update_record, update_customer, or update_account.

Code execution

execute runs TypeScript against the full Conductor API through the Node.js SDK, for multi-step jobs, loops over many records, and the few operations no other tool covers. The AI tool uses it instead of calling the same tool once per record, page, or date range, and to total or filter more records than one result holds. It’s on the root address only, including its read-only address. The AI tool writes an async function run(conductor) that returns the data to keep, and any console.log output comes back with it. The code is type-checked against the SDK before it runs, so a type error comes back as the result, and it can reach only the Conductor API. For example, to total unpaid invoices by customer:
  • Every conductor.qbd method needs conductorEndUserId: a company file id from list_company_files or conductor.endUsers.list().
  • QuickBooks Desktop answers one request at a time, so the code awaits each request before the next and puts several ids in one request. A cursor stops working 20 seconds after the previous page, so a page loop finishes inside one call.
  • A call stops after about 5 minutes, or 50 seconds through the conductor-node-mcp package except in Claude Code. Variables don’t persist between calls, so a large job is split across calls. In Codex CLI, set tool_timeout_sec = 300 as in step 3 of its setup.
  • The code can be up to 60,000 characters, and a result over 30,000 characters is cut at that length.
  • A key can run 2 execute calls at once, besides its 10 tool calls.
  • Writes change the company’s books, and nothing undoes them. After a timeout, check what was saved before running the code again.
  • On a read-only connection, the code runner refuses code that names one of the SDK’s write methods, so reads run and such a write fails before it starts. This guards against the AI tool making a change by accident; it isn’t a security boundary, and the key itself can still write through the Conductor API until Conductor has read-only keys, which will enforce read-only on the API itself.

How the tools work

Company file

Every tool except list_company_files, describe_operation, and execute takes an optional companyFileId. When your project has one connected company file, the tools use it. With several, the AI tool passes one of the ids that list_company_files returns, and a call without one fails with MULTIPLE_COMPANY_FILES, which names the files. A file that has never answered a request is listed but never picked on its own. Every result from QuickBooks names the company file it came from.

Lists and paging

  • A list returns at most 150 records per call. The default is 25 for transactions, 50 for customers, vendors, classes, and items, and 150 for accounts; limit sets another number from 1 to 150.
  • Customer, vendor, class, and item lists return a nextPageToken when more records match, and the AI tool passes it back for the next page. Transaction lists, list_records, and name lists filtered by part of a name return hasMore instead (transaction lists and list_records add remainingCount), so the AI tool narrows the dates or filters to reach the rest.
  • list_accounts has no paging; in a file with more than 150 accounts, the AI tool narrows by accountType or nameContains. list_payments_to_deposit returns every waiting payment in one call.
  • Filters named ids, fullNames, names, and refNumbers match exactly, and one unknown value fails the request. nameContains, nameStartsWith, and refNumberContains match part of a value.
  • Transaction lists leave out line items unless includeLineItems is true, which is the default when the call passes ids.

Large results

A result holds at most 30,000 characters. A longer one loses records from the end and carries truncated: true, and its paging fields continue from the last record returned, so nothing is skipped. Reports have no paging, so a truncated report needs a shorter period or narrower filters. On the root address, including its read-only address, a truncated result, or a page reached with nextPageToken that still has more, also carries a hint that points the AI tool to execute, which can read every page or the whole report in one call and return only what’s needed. An execute result over 30,000 characters is cut at that length.

Changes

  • In Claude, read tools run without asking, and each write tool asks before it runs unless you chose Always allow for that tool. Other AI tools ask according to their own settings.
  • A create adds one record. Repeating it creates a second invoice, bill, check, payment, deposit, or journal entry; QuickBooks rejects a second customer, vendor, or account with the same name.
  • An update needs the record’s id and current revisionNumber, which the list tools return, and QuickBooks rejects it if the record changed since. Fields left out stay as they are, but lines you send replace all of the record’s lines (for a received payment, the invoices it pays), so include every line to keep.
  • A QuickBooks write tool takes at most 200 lines.
  • Write tools change records in QuickBooks only. They don’t move money, contact a bank, or print or send anything; isQueuedForPrint and isQueuedForEmail only add the record to QuickBooks’ own print or email queue.

Errors

A failed call returns text the AI tool can act on: a code, what went wrong, and one next step, such as COMPANY_FILE_NOT_FOUND: No company file with id 'end_usr_123' in this project. Call list_company_files and pass one of its ids as companyFileId. Codes from the Conductor API mean what Error handling says; these come from the MCP server:

Logs

Tool arguments, including the code sent to execute, and results are logged for 30 days, as API request and response bodies are. See Security and data retention.

Timeouts and limits

Every tool call except list_company_files and describe_operation reaches QuickBooks Desktop through the Web Connector on the computer that holds the company file, so QuickBooks Desktop and the Web Connector must be running there.
  • QuickBooks Desktop answers one request at a time for each company file. Calls to the same file wait their turn, so asking for several things at once doesn’t make them faster.
  • The first request after a pause can take 3 to 10 seconds, and up to 90 seconds when the Web Connector must open the company file.
  • When QuickBooks doesn’t answer in time (90 seconds, or 50 seconds through the conductor-node-mcp package except in Claude Code), the call fails with QBD_REQUEST_TIMEOUT. A create or update that timed out may still have been saved, so check with the matching list tool before repeating it.
  • execute stops a call with EXECUTE_TIMEOUT after about 5 minutes, or 50 seconds through the conductor-node-mcp package except in Claude Code.
  • A key can run 10 tool calls and 2 execute calls at once; more can return RATE_LIMITED until one finishes.