DeepLedger
Menu

For developers

Connect Hermes Agent to QuickBooks Online with DeepLedger MCP

Add DeepLedger's hosted MCP server to Hermes Agent with OAuth or an API key, require approval before any write, and verify one QuickBooks report.

Published by DeepLedgerUpdated 10 min read

Hermes Agent connects to QuickBooks Online through DeepLedger's hosted MCP server: add https://mcp.deepledger.ai/mcp with hermes mcp add and sign in with your DeepLedger account or a DeepLedger API key. Hermes is the open-source agent from Nous Research that runs in your terminal, a desktop app or a messaging gateway. You add DeepLedger once, Hermes discovers the accounting tools, and you start with a report you can check against QuickBooks before it records anything.

Connection settingValue
Server URLhttps://mcp.deepledger.ai/mcp
TransportStreamable HTTP
AuthenticationOAuth (browser sign-in) or Authorization: Bearer <DeepLedger API key>
Hermes config file~/.hermes/config.yaml, under mcp_servers

What are you connecting?

DeepLedger runs a hosted QuickBooks MCP server. An admin connects each QuickBooks Online company to DeepLedger once, through Intuit's sign-in. Hermes then signs in to DeepLedger as you. Hermes never sees Intuit credentials, and you don't need an Intuit developer app.

Hermes sends tool results to the model provider you configured. Before connecting real client books, confirm that provider is approved for financial data.

Before you start

  • A DeepLedger account with access to the QuickBooks Online company you plan to use.
  • The company connected: in DeepLedger, open Companies, select the company, open its Connections tab and choose Connect to QuickBooks.
  • Hermes Agent installed and set up with a model provider. Run hermes update if your install is older than the September 2026 releases; this guide was checked against v2026.9.24.
  • A demo company for the first session.

Should Hermes sign in with OAuth or an API key?

OAuthAPI key
Best forHermes on your own computer, or the Hermes desktop appA Hermes messaging gateway (Telegram, Slack and similar) or a server with no browser
Secret storedToken in ~/.hermes/mcp-tokens/deepledger.jsonKey in ~/.hermes/.env
CompaniesEvery company you can accessAll my companies, or One company if you choose it
Revokehermes mcp remove deepledger, and Settings → Connected apps in DeepLedgerSettings → API keys in DeepLedger

Either way, the connection acts as the DeepLedger user who authorized it, with that person's access. There is no read-only switch on either.

How do I connect Hermes Agent to QuickBooks Online?

Step 1: Add DeepLedger to Hermes

Run hermes mcp add with the DeepLedger URL and sign in with your DeepLedger account, or paste a DeepLedger API key when Hermes asks.

With OAuth:

hermes mcp add deepledger --url https://mcp.deepledger.ai/mcp --auth oauth

Hermes opens your browser. Sign in with your DeepLedger account and approve access. DeepLedger supports OAuth discovery and dynamic client registration, so there is no client ID or token to paste.

With an API key: any team member can create one.

  1. In DeepLedger, open Settings → API keys and choose Create key.
  2. Name it for this machine, pick an Expiration, and choose All my companies or One company.
  3. Copy the key. It starts with dl_live_ and is shown once.
  4. Add the server with header authentication:
hermes mcp add deepledger --url https://mcp.deepledger.ai/mcp --auth header

Answer yes when Hermes asks whether the server requires authentication, then paste the key at the API key / Bearer token prompt. Hermes saves it to ~/.hermes/.env as MCP_DEEPLEDGER_API_KEY and writes only a reference to it in config.yaml. Don't paste the key into a chat with the agent.

Step 2: Start with a small set of tools

After it connects, Hermes lists DeepLedger's tools and asks:

Enable all N tools? [Y/n/select]:

Type select and keep only these four for your first session:

  • qbCompanyProfile: lists and switches companies
  • qbReports: financial reports
  • qbFetchTransactions: transaction lookups
  • getGuide: DeepLedger's working guides

Hermes records your choice as tools.include. Change it later with hermes mcp configure deepledger.

Step 3: Require approval before writes

Add trust: untrusted to the DeepLedger entry in ~/.hermes/config.yaml. The entry should look like one of these:

mcp_servers:
  deepledger:
    url: "https://mcp.deepledger.ai/mcp"
    auth: oauth
    trust: untrusted
    tools:
      include: [qbCompanyProfile, qbReports, qbFetchTransactions, getGuide]
mcp_servers:
  deepledger:
    url: "https://mcp.deepledger.ai/mcp"
    headers:
      Authorization: "Bearer ${MCP_DEEPLEDGER_API_KEY}"
    trust: untrusted
    tools:
      include: [qbCompanyProfile, qbReports, qbFetchTransactions, getGuide]

With trust: untrusted, Hermes asks before it runs any DeepLedger tool that the server does not mark read-only. DeepLedger marks qbReports, qbFetchTransactions and getGuide as read-only. Every other tool asks first, including qbCompanyProfile, because switching companies changes which books later calls use. Without the line, Hermes treats the server as fully trusted and calls write tools without asking.

Run /reload-mcp in an open session, or start a new one.

Step 4: Check the connection

Run hermes mcp test deepledger, then ask Hermes which DeepLedger tools are available.

hermes mcp test deepledger
hermes mcp list

In a session, ask "Tell me which DeepLedger tools are available right now." Hermes names them with a server prefix, such as mcp_deepledger_qbReports.

How do I run Hermes without a browser?

DeepLedger does not support the device-code flow, so hermes mcp login deepledger --flow device will not work. On a remote host, pick one:

  • Use an API key. This is the simplest choice for a gateway or a server.
  • Forward the callback port. Set a fixed port under oauth: { redirect_port: 27890 } in the server entry. Run ssh -N -L 27890:127.0.0.1:27890 you@host from your laptop, then open the sign-in link there.
  • Paste the redirect. If the browser can't reach the callback, Hermes offers to take the redirect URL at its prompt.
  • Use the desktop app. It relays the OAuth callback from your machine to a remote backend.

On a gateway, find out how approval requests reach you before you add write tools. If you schedule Hermes jobs, the schedule is Hermes's feature: each run acts as the person whose sign-in or key it uses, and DeepLedger only answers those requests.

Next step: verify one company and one report

With DeepLedger enabled in Hermes, ask:

Using DeepLedger, list the companies I can access and identify the active company. Ask me which company to use, then switch to it and confirm its name. Do not create or change accounting records.

Approve the switch when Hermes asks. Your active company carries over to your other connected AI apps, so confirm it when you change sessions; a One company key can't switch. See selecting the right QuickBooks company.

Then a bounded report:

Using DeepLedger for [confirmed company], retrieve the profit and loss for September 1 through September 30, 2026, on an accrual basis. Show the company name, dates, basis, currency, income, expenses and net income. Do not create or change accounting records.

In QuickBooks Online → Reports → Profit and Loss, run the same company, dates and basis, and compare income, expenses and net income. If totals differ, fix the context and rerun. Follow the P&L analysis and verification workflow for what to compare.

What can Hermes do in QuickBooks after connecting?

DeepLedger works when you ask: Hermes acts only when you tell it to. Add the tools a task needs to tools.include first.

  • Purchases: bills, expenses, bill payments and vendor credits (qbBill, qbExpense, qbPayment).
  • Sales: estimates, invoices, payments and sales receipts (qbEstimate, qbInvoice, qbSalesReceipt).
  • Other transactions: deposits, transfers and journal entries (qbDeposit, qbTransfer, qbJournalEntry).
  • Reports: standard reports and saved custom reports (qbReports, customReports).
  • Client rules: the company's AI Brain (agentMemory) and Company Skills (skills). Ask Hermes to read them before it codes transactions.
  • Tasks: questions and handoffs to a person (tasks).

A first real task once the report agrees:

Using DeepLedger for [company], read the company's AI Brain and skills, then prepare an unpaid bill from this vendor invoice. Check for duplicates, propose the expense categories, and show me the bill before recording it.

Is it safe to let Hermes write to QuickBooks?

Yes, with trust: untrusted on and a person reading each proposed write. DeepLedger adds these on the server:

  • Every write must carry its company (companyId). If it is missing or differs from the active company, DeepLedger refuses with COMPANY_REQUIRED or COMPANY_MISMATCH and nothing is written.
  • Voids and deletes need confirmation. A void keeps the record; a delete of a posted transaction is refused on or before the company's closing date.
  • Duplicate and open-document checks on supported recording paths.

DeepLedger also instructs the AI to send uncertain work to Tasks for a person to decide. That is guidance the AI follows, not a server lock, so review what it proposes.

Hermes keeps session history and its own long-term memory on the machine where it runs. Report figures and transaction details can end up there, so protect that machine as you would any copy of client financial data. DeepLedger records each tool call in its own Audit history, separate from Hermes. More in AI write access to QuickBooks, safely.

Troubleshooting

DeepLedger is missing. Check hermes mcp list and confirm the entry doesn't say enabled: false. After editing config.yaml, run /reload-mcp or start a new session.

401 or 403. For OAuth, run hermes mcp login deepledger and sign in with the right DeepLedger account. For an API key, check that MCP_DEEPLEDGER_API_KEY in ~/.hermes/.env is complete and hasn't expired or been revoked. hermes logs --level debug shows the failing request.

A tool is missing. It is probably not in tools.include. Add it with hermes mcp configure deepledger.

Every call asks for approval. That is expected for write tools under trust: untrusted. Reports and transaction lookups shouldn't ask; if they do, update Hermes.

A write fails with COMPANY_MISMATCH. Another app switched your active company. Nothing was written. Confirm the company and try again.

Reports fail after a successful switch. That company's QuickBooks connection needs an admin to reconnect it on its Connections tab in DeepLedger.

Disconnect. hermes mcp remove deepledger removes the server from Hermes. If you used an API key, revoke it under Settings → API keys. Neither step deletes accounting records or disconnects QuickBooks from DeepLedger.

Checked against the Hermes Agent documentation and v2026.9.24 source in October 2026.

Documentation and configuration last verified October 5, 2026. This guide was checked against the linked vendor documentation and DeepLedger's server implementation. We did not complete a new OAuth grant or retrieve an account-level report in this client during this revision. The prompts are suggested checks, not claimed test results. Have the account owner complete sign-in and the demo-company report comparison above before using business data.

Frequently asked questions

How do I connect Hermes Agent to QuickBooks Online?

Run hermes mcp add deepledger --url https://mcp.deepledger.ai/mcp --auth oauth and sign in with your DeepLedger account. Your QuickBooks Online company must be connected in DeepLedger first. Hermes then discovers DeepLedger's QuickBooks tools, and you choose which ones to enable.

Does Hermes Agent support remote MCP servers?

Yes. Hermes Agent from Nous Research ships MCP support without an extra install. Servers live under mcp_servers in ~/.hermes/config.yaml, and a remote server needs only a url. Hermes handles OAuth discovery, client registration, PKCE and token refresh for servers that support it, which DeepLedger does.

Should I use OAuth or an API key with Hermes?

Use OAuth on a computer where you can open a browser. Use a DeepLedger API key when Hermes runs as a messaging gateway or on a server with no browser, because DeepLedger does not offer the device-code sign-in flow. Any team member can create a key under Settings, API keys, Create key, and both routes act as the person who authorized them.

Can Hermes ask me before it changes my books?

Yes. Add trust: untrusted to the DeepLedger server in config.yaml. Hermes then asks for approval before calling any tool that the server does not mark read-only. DeepLedger marks reports, transaction lookups and its guide as read-only, so those run without a prompt and everything else waits for you.

Which model sees my QuickBooks data?

Whichever model provider Hermes is configured to use. Tool results, including report figures and transaction details, go into that model's context. Use a provider your organization has approved for financial data, or a local model if you need inference to stay on your hardware.

Can Hermes run QuickBooks work on a schedule?

Only if you schedule it in Hermes or your own job runner. A scheduled Hermes job runs as the person whose sign-in or API key it uses. DeepLedger does not start anything on its own; it only answers the requests Hermes sends.

Browse all AI platforms and integrations.

Ready to get started?

Connect QuickBooks and try your first task with an AI agent.

Create an Account

With your permission, Google Analytics measures visits to our public website and blog. Essential cookies work either way. Change your choice in Cookie settings. Privacy policy