Using the Mercury Books API and MCP

Connect an AI tool like Claude, ChatGPT, or Cursor to ask questions about your financials and make changes in plain language, or use the Books API to build your own scripts and integrations. This article explains what each one does, how to set it up, and what isn't supported yet.

Before you start

You'll need:

  • An active Books subscription. Books is turned on for your organization
  • The right permissions. Your Mercury role can manage Books and see all accounts. The Mercury Books toggle on a role turns on everything you need. See our Sharing access to your books article


Note: Each connection works with one organization's books. If you're a bookkeeper or accountant, connect once for each client.

Which one to use

  Books MCP Books API
Best for Asking questions and making changes in plain language from an AI tool Scripts, scheduled jobs, and integrations you build and run yourself
Who sets it up Anyone with the right permissions. No code needed A developer comfortable making API requests
How you sign in Sign in to Mercury in your browser and grant access to one organization An API token created in Mercury settings
Example "Pull a monthly profit and loss for the last three months" A nightly job that categorizes new Stripe deposits and posts depreciation

Both work on the same books. A change made through one shows up in Books, and in the other, right away.

Connecting an AI tool with Books MCP

Books MCP uses the Mercury MCP address: https://mcp.mercury.com/mcp

Claude.ai

  1. Go to Settings > Connectors and click Add custom connector
  2. Paste the server address above
  3. Sign in to Mercury and grant access to one organization


If you can't add a custom connector, ask your Claude workspace admin to allow them.

Claude Code

  1. Run claude mcp add --transport http -s user mercury https://mcp.mercury.com/mcp
  2. Run claude mcp login mercury, then sign in to Mercury in your browser and grant access to one organization
  3. Run claude mcp list and check that mercury shows as connected

Codex CLI

  1. Run codex mcp add mercury --url https://mcp.mercury.com/mcp
  2. Sign in to Mercury in your browser. If no browser opens, run codex mcp login mercury
  3. Run codex mcp list and check that the Auth column shows OAuth

Other AI tools

Add the server address as a streamable HTTP server and let the tool handle sign-in. If it can't find where to sign in, give it https://mcp.mercury.com/.well-known/oauth-protected-resource.

Try it

Once connected, try asking:

  • "Pull a monthly profit and loss report for the last three months."
  • "Show the balance sheet as of the end of last month."
  • "Find my uncategorized transactions from October and suggest a category for each."


Tip: Changes made through Books MCP post to your books right away, so ask your AI tool to show you what it plans to change before it applies anything, especially for bulk changes.

For everything your AI tool can do, see Supported tools on Mercury's MCP.

Using the Books API

  1. Create an API token in Settings > API tokens. The token acts as the user who creates it, so that user needs the permissions above
  2. Call GET /books/instances to confirm the token can reach your books
  3. Call GET /books/ledgers to get your chart of accounts. Most other requests refer to accounts by their ledger ID
  4. Call GET /books/source-accounts to find the bank and card accounts that feed your books


For every endpoint and step-by-step workflows, see the Books API reference and the Books API Use Cases.

Tip: Treat your API token like a password. If it's ever exposed, revoke it in settings and create a new one. See API token security policies.

What you can do

The MCP and the API cover the same parts of Books.

  • Transactions. Find uncategorized transactions, then categorize or split them across accounts
  • Categorization rules. View, create, and delete rules that categorize future transactions
  • Journal entries. Create, edit, and delete journal entries, and search them by date, account, amount, or description
  • Chart of accounts. Add, rename, renumber, nest, and delete accounts, and set opening balances. With the MCP, you can describe the changes you want or upload a chart of accounts to convert to
  • Bills and invoices. Record bills and invoices, edit them, and match bank transactions to the ones they paid
  • Reports. Pull a profit and loss, balance sheet, or cash flow report for any period, and drill into an account's balance and activity

What isn't supported

  • Closing periods and reconciling accounts
  • Matching or unmatching transfers between accounts. A transaction matched to a transfer must be unmatched in Books before it can be recategorized
  • Editing an existing categorization rule. Delete it and create a new one instead
  • Creating tags, or connecting and unlinking bank, card, and integration feeds
  • Changing accounts linked to a Mercury bank or card account, which are read-only
  • One connection or token across several client organizations


Note: New categorization rules apply only to transactions categorized from then on. They don't change existing transactions. See our Managing categorization rules article.

Troubleshooting

I see "Your organization doesn't have access to this route." 

Books isn't turned on for your organization, or your role is missing a Books permission. Check both, then try again.

My AI tool is connected but can't see my books. 

You probably added Mercury from your AI tool's connector directory, which doesn't include Books tools yet. Remove it and add https://mcp.mercury.com/mcp as a custom connector.

I can read my books but can’t make changes.

Your connection doesn’t have the Books write permissions. Reconnect Mercury in your AI tool (or disconnect and add it again), and grant them on the sign-in screen.

I'm getting authentication errors. 

Your session may have ended. Sign in again with claude mcp login mercury or codex mcp login mercury, or reconnect the connector in your AI tool.

API requests return 403. 

The token's user is missing a Books permission or can't see all accounts. Update their role, then try again.

I don't see a change my AI tool says it made. 

Open the transaction or journal entry in Books to check. If the change returned an error, it may still have gone through, so look before asking your AI tool to try again.


FAQs

Do changes to my books made through the MCP or API need approval?

No. They post right away, the same as changes you make in Books.

Can my firm use one connection for all our clients? 

Not today. Connect, or create a token, once for each client organization.

Is there an extra cost? 

No. The API and MCP are included with Mercury Books.

How do I share feedback or ask for a new capability? 

Email api@mercury.com.

Related articles

 

Mercury is a fintech company, not an FDIC-insured bank. Banking services provided through Choice Financial Group and Column N.A., Members FDIC.

AI-generated responses and suggested actions may vary and are not guaranteed. Please review outputs before taking action.

Did you find this article helpful?