Troubleshooting
QuickBooks reconnect
The QuickBooks MCP connection drops when the OAuth token expires, the connected company changes, or the Intuit developer app credentials are rotated. Follow the steps below to reconnect.
Signs of a dropped QuickBooks connection
- !The Operator created an escalation card mentioning quickbooks.
- !The activation checklist shows the Bookkeeper MCP step as red.
- !No Bookkeeper reconciliation report this week despite the scheduled run.
- !claude mcp list shows quickbooks as error or disconnected.
Step 1: Check the error
claude mcp listThe most common errors from QuickBooks are:
token_expired
OAuth refresh token expired (after 100 days of inactivity). Proceed to Step 2.
invalid_client
Client ID or secret changed. Get new credentials from developer.intuit.com and proceed to Step 3.
company_not_found
The realm ID changed (new QuickBooks company or subscription change). Update the realm ID in Step 3.
Step 2: Re-authorize via OAuth
Re-running the claude mcp add command for QuickBooks will open a browser window for re-authorization. Complete the QuickBooks login flow in the browser. The MCP client captures the new tokens automatically.
claude mcp add quickbooks \
--client-id YOUR_CLIENT_ID \
--client-secret YOUR_CLIENT_SECRET \
--realm-id YOUR_REALM_IDA browser window will open asking you to sign in to QuickBooks and authorize access. After completing the flow, the terminal confirms the connection.
Step 3: Find your credentials (if changed)
Client ID and Secret
- Go to developer.intuit.com.
- Open your app → Keys & credentials.
- Copy the production Client ID and Client Secret.
Realm ID
Log in to QuickBooks Online. The realm ID appears in the URL as the number after?cid= or in your account settings under Company ID.
Step 4: Verify
claude mcp listThe quickbooks entry should show as connected. The Bookkeeper runs next on its scheduled Monday or month-start cadence. If you need to run a reconciliation immediately, trigger it from the portal event log.