How to connect QuickBooks Desktop to Codex CLI (MCP server setup)
Run one codex mcp add command so Codex CLI can read and write QuickBooks Desktop and QuickBooks Enterprise company files through Conductor's MCP server. The guide also covers the browser sign-in, the bearer-token setup for machines without a browser, read-only mode, and the errors a Codex setup can hit.
To connect QuickBooks Desktop to Codex CLI, run codex mcp add conductor --url https://mcp.conductor.is/ in a terminal and sign in to Conductor when Codex opens your browser. Codex CLI then reads and writes QuickBooks Desktop and QuickBooks Enterprise company files through Conductor's MCP server. You need a Windows computer running QuickBooks and the QuickBooks Web Connector, plus a Conductor account. Setup takes three steps, with no API key to copy.
Before you start
Codex CLI can reach a company file only after that file is connected to a Conductor project. Have these in place first:
A Windows computer that holds the company file and keeps QuickBooks Desktop and the QuickBooks Web Connector running.
A supported edition: QuickBooks Enterprise Solutions of any version or year, or QuickBooks Premier (Plus), QuickBooks Desktop Pro (Plus), or QuickBooks Accountant Desktop (Plus), each 2018 or later. QuickBooks Desktop for Mac does not work because it has no Web Connector.
A Conductor account with a project that holds the company file's connection. Sign up in the Conductor Dashboard. The QuickBooks user makes that connection once by opening a config file from Conductor in the Web Connector, as how to open or import a QWC file shows.
Codex CLI, installed and signed in. Codex can run on a different computer from QuickBooks, such as a Mac or a Linux server. On a personal ChatGPT plan that can't add a custom MCP server, Conductor's setup guide recommends Codex CLI.
Conductor's Production tier costs $49 per company file per month, with no platform fee and no monthly minimum. The Trial tier is free and includes 1 connection for testing and development.
Add the Conductor MCP server to Codex CLI
Adding Conductor to Codex CLI takes one codex mcp add command and a browser sign-in. Keep QuickBooks and the Web Connector running on the Windows computer connected to Conductor while you do this. The command below adds Conductor for all your Codex projects:
Run the
codex mcp addcommand above in a terminal, as the Codex CLI tab of Conductor's MCP setup guide shows. If you already added Conductor, runcodex mcp remove conductorfirst.Sign in to Conductor in the browser window that Codex opens, pick your project, and click Allow. If Codex instead tells you to run
codex mcp login conductor, run it to open the sign-in.Start Codex and ask your question. The first time Codex runs a Conductor tool, it asks for permission; choose Always allow so it stops asking.
Signing in adds an "MCP (Codex)" key to your Conductor project's API Keys page. To revoke Codex CLI's access later, delete that key. Codex saves the server entry in ~/.codex/config.toml, and OpenAI's Codex MCP documentation describes that file and its bearer_token_env_var setting.
For read-only access, run this command in step 1 instead:
Connect Codex CLI on a machine without a browser
On a machine without a browser, such as a server you reach over SSH or a container, Codex CLI connects with a Conductor API key that it reads from an environment variable. The QuickBooks side does not change: QuickBooks and the Web Connector keep running on the Windows computer connected to Conductor.
Skip step 2 above. Create a key on your project's API Keys page in the Conductor Dashboard, then run the step 1 command with --bearer-token-env-var CONDUCTOR_SECRET_KEY added:
Set CONDUCTOR_SECRET_KEY to the key in your shell profile, then open a new terminal before you start Codex. Codex saves only the variable's name in ~/.codex/config.toml and sends the variable's value as a bearer token in the Authorization header, so the key itself never lands in the config file. For a read-only connection without a browser, put https://mcp.conductor.is/read-only in the same command.
Check that it works
To check that Codex CLI can reach your company file, start Codex and ask: Show the 5 most recent invoices using my most recently successful QuickBooks Desktop connection. If Codex returns real invoices from that company file, the setup works.
A server that shows as connected proves only that the sign-in or config worked, because Conductor checks the key on the first request.
To test a read-only connection, ask Codex CLI to create a test customer in QuickBooks. If Codex can't, read-only mode is on. If it can, Codex still has full access, so check the URL in your codex mcp add command.
What this does and does not do
With the full-access URL, Codex CLI reads and writes data in every company file connected to the Conductor project you picked at sign-in. To limit Codex CLI to certain company files, connect it to a Conductor project that holds only those files' connections.
Conductor works with QuickBooks Enterprise, Premier, Pro, and Accountant on Windows. Conductor does not connect to QuickBooks Online, which is a different product. Intuit's own QuickBooks Online connector for ChatGPT covers that product.
For a company file hosted by Rightworks, someone must stay connected to the Rightworks remote desktop session with QuickBooks open, because Rightworks stops all background programs when you disconnect. Conductor's Rightworks guide covers the Web Connector setup there.
The read-only URL, https://mcp.conductor.is/read-only, blocks creates, updates, and deletes before they reach QuickBooks. Use it for a trial, an accountant, or co-workers who should only read. The URL limits the connection, not the Conductor key. In the words of Conductor's docs: "Read-only mode is a guardrail, not a security boundary: anyone with the Conductor key can still write through the Conductor API." Give each person their own key, as signing in does, and revoke it when needed.
Setting | Full access | Read-only |
|---|---|---|
URL |
|
|
Codex CLI command |
|
|
Creates, updates, and deletes | Reach QuickBooks | Blocked before they reach QuickBooks |
When to use | Codex CLI should create or change records | A trial, an accountant, or co-workers who should only read |
How this works
Codex CLI reaches a company file in two hops: an MCP call to Conductor's server, then the QuickBooks Web Connector on the Windows computer that holds the file. MCP (Model Context Protocol) is an open standard that lets an AI application such as Codex CLI call tools that run on an outside server. Conductor's hosted MCP server at https://mcp.conductor.is/ connects QuickBooks Desktop and QuickBooks Enterprise to Codex CLI.
Conductor's MCP server exposes two tools. search_docs searches the documentation for Conductor's API and TypeScript SDK. execute runs code that Codex writes against that SDK in an isolated sandbox with no web or filesystem access, then hands back whatever the code returns or prints. A question about overdue invoices becomes a short program that lists invoices inside execute, and Codex summarizes the rows it gets back.
Requests reach the company file through the QuickBooks Web Connector, a Windows program that ships with every version of QuickBooks Desktop and runs in the background on the computer that holds the file. A QuickBooks user sets up that connection once through Conductor's authentication flow: download a config file, open it in the Web Connector, and authenticate. From then on, Conductor forwards each request to the Web Connector, which passes it to QuickBooks, and the response travels back the same way.
Codex CLI never talks to the Windows computer directly. Codex sends its requests to the hosted server over HTTPS, so Codex can run anywhere, including on a Mac or a Linux server, and connecting it needs no Web Connector changes.
If it does not work
If Codex CLI can't connect or its requests fail, find the message or symptom you see below. Each entry matches one in Conductor's MCP troubleshooting docs.
Couldn't reach the MCP server
"Couldn't reach the MCP server" means the URL in your codex mcp add command isn't https://mcp.conductor.is/ or https://mcp.conductor.is/read-only. Run codex mcp remove conductor, then run the step 1 command again with the URL exactly as written. The troubleshooting entry lists both URLs.
Authorization with the MCP server failed
Conductor's troubleshooting docs say "Authorization with the MCP server failed" means the Conductor sign-in didn't finish. Sign in with the email your company uses for Conductor (on the Conductor page that opens, click Use a different account), or ask a teammate to add you on the Members page. Then run codex mcp remove conductor and the step 1 command again to connect.
API key missing or invalid (if you pasted a key)
On a setup without a browser, "API key missing or invalid" means the key Codex CLI reads from CONDUCTOR_SECRET_KEY is missing or isn't a valid Conductor key. Create a new key on your project's API Keys page, set CONDUCTOR_SECRET_KEY to it in your shell profile, then open a new terminal and restart Codex. The troubleshooting docs give the same fix: a new key, then a restart.
Requests to QuickBooks fail
The usual cause is that QuickBooks Desktop or the Web Connector isn't running on the computer connected to Conductor. Make sure both are running on that Windows computer, then ask Codex CLI again. Connecting Codex CLI needs no Web Connector changes, as the troubleshooting entry notes.
I see SEO tools, not QuickBooks (wrong Conductor)
Tools such as ai_brand_insights and keyword_insights mean Codex CLI is connected to the MCP server of an unrelated SEO company at conductor.com. Remove that server with codex mcp remove and the name you gave it, then run the step 1 command with https://mcp.conductor.is/. The QuickBooks server at conductor.is has only the execute and search_docs tools, as the troubleshooting docs note.
Frequently asked questions
Does this work with QuickBooks Enterprise?
Codex CLI connects to QuickBooks Enterprise company files of any version or year with the same codex mcp add command. QuickBooks Enterprise is a tier of QuickBooks Desktop and uses the same Desktop SDK and Web Connector as Pro, Premier, and Accountant.
Does QuickBooks Desktop need to be open?
QuickBooks and the Web Connector must be running on the Windows computer connected to Conductor whenever Codex CLI sends a request. Codex CLI itself can run on any computer.
Can I give Codex CLI read-only access?
Codex CLI gets read-only access when you add the server with https://mcp.conductor.is/read-only in place of https://mcp.conductor.is/. The key behind that connection still has full access through the Conductor API.
What does it cost?
Conductor charges $49 per month for each established company file connection in use. A connection is in use when an API call reached it within the rolling past month. Connections to QuickBooks sample company files are free.
Can co-workers connect with their own Codex CLI?
Co-workers can each connect their own Codex CLI, as long as they are members of your Conductor organization. Each one runs the same command and signs in with their own account, which creates a separate key. Pricing is per company file, so more co-workers, keys, or AI tools cost nothing extra.
Connect QuickBooks Desktop to other AI tools
Each tool guide below connects the same Conductor MCP server to another AI tool. The first link compares the MCP server options for QuickBooks, and the last covers what AI agents can do once connected.
