Connect your AI

Connect Hermes to your bank accounts

Use OpenBudget to give Hermes live access to your transactions, balances, debts, and categories.

Hermes Agent supports the Model Context Protocol (MCP), which lets it connect directly to your OpenBudget account. When you ask about spending, balances, debts, or categories, Hermes can use your current records in its answer. Install the OpenBudget finance skill so Hermes chooses the right tools and asks before changing a record. Here's how to set it up in a few minutes.

Let Hermes set it up

Copy this prompt into Hermes. It will run the commands, pause when it needs browser approval, and continue after you return.

Set up OpenBudget for this Hermes installation. Follow this execution contract exactly.

Use the terminal tool to start this exact command with background=true, pty=true, and notify_on_complete=true:
hermes mcp add openbudget --url "https://api.openbudget.sh/mcp" --auth oauth

Keep --url and its quoted HTTP URL together on that one command line. Never change --url to @url:, and never execute the URL as a shell command. Save the returned process session_id and poll that same session for output. If it asks whether to overwrite an existing openbudget entry, write y followed by Enter to that process.

When the process prints an authorization URL, send me the complete authorization URL and wait for me. Keep the same background process and PTY alive while I approve access. Do not ask me for the localhost callback URL or authorization code, do not exchange a code yourself, and do not start a second OAuth command. The callback code is single-use and belongs to the PKCE verifier held by that exact process.

After I say the browser flow finished, poll the same process session. If it asks whether to enable all tools, send Enter to accept the default. Continue polling until the command exits and its output confirms that openbudget was saved. Then run hermes skills install https://api.openbudget.sh/.well-known/skills/openbudget-finance/SKILL.md --now and hermes mcp test openbudget as exact commands. If the test succeeds, tell me OpenBudget is connected, send me to {{CURRENT_ORIGIN}}/accounts to connect my first bank account, and wait for me to finish before using any finance tools.

If the background process exits before confirming that openbudget was saved, stop and show me its exact output. Explain that any authorization code from that attempt cannot be reused. Do not install the skill or run the test. If the terminal or process tools are unavailable, tell me to use the manual steps instead.

The full walkthrough below lets you run each command yourself.

How to connect

Add the OpenBudget MCP server

Run this command to add OpenBudget. Follow the authorization link Hermes prints, then sign in and approve access.

$ hermes mcp add openbudget --url "https://api.openbudget.sh/mcp" --auth oauth

Leave this command running while you approve access. Hermes captures the localhost callback itself, so do not paste the callback URL or code into a second command.

Install the OpenBudget finance skill

Install the finance skill so Hermes chooses the right tools and asks before changing a record.

$ hermes skills install https://api.openbudget.sh/.well-known/skills/openbudget-finance/SKILL.md --now

Verify the connection

Run a connection test and confirm Hermes can see the OpenBudget tools.

$ hermes mcp test openbudget

Connect your bank accounts

Get started with OpenBudget to securely link your bank accounts and credit cards through Plaid. Free for 7 days.

Secured by

Plaid

Get started

Currently available for United States banking institutions.

Now just ask.

Ask about spending, balances, debts, or categories and Hermes will call OpenBudget when it needs your current records.

Hermes calls OpenBudget automatically when your question needs current account data.

Try asking

Works across Hermes sessions

You can keep using the same connection in later Hermes sessions. The finance skill helps Hermes choose the right tools and ask before changing a record.

Your banks stay protected

Plaid keeps your bank credentials. Hermes never receives them. Hermes can organize records in OpenBudget when you approve it, and it can't move money or change anything at your bank.

Troubleshooting

My AI doesn't see OpenBudget's tools

Make sure the connector is added andenabled, and that you finished the OAuth sign-in. If it still won't use them, ask it directly to “use the OpenBudgetMCP server.” In ChatGPT, start the message with @OpenBudget.

It can't find my transactions

The MCP server only sees accounts you've linked. Open your transactions, confirm your banks are connected and finished their initial sync, then ask again. Make sure you signed in to OpenBudget with the same account you used to link your banks.

The sign-in window didn't open

Authorization happens in your browser. If it didn't open automatically, allow pop-ups and try again, or copy the URL your client shows and open it manually. In Claude Code, run /mcp and choose Authenticate; in the Codex CLI, run codex mcp login openbudget.

It says “needs login” or stopped working

Sign-in tokens can expire. Re-authorize from your client's connector settings, or remove and re-add the OpenBudget server and sign in again — that resolves most connection issues.

Connection failed or the server is unreachable

Confirm the URL is exactly https://api.openbudget.sh/mcp and that you chose the Streamable HTTP transport (not stdio). Make sure your client is up to date — the older SSE transport is deprecated in favor of HTTP.

Still stuck?

Email support@openbudget.sh and we'll help you get connected.

Disclosures

Informational only — not financial advice

OpenBudget surfaces your own financial data, not recommendations. Nothing here is investment, legal, or tax advice — do your own research.

How your data is accessed

OpenBudget connects through Plaid; your bank credentials are never stored by OpenBudget. Data may contain errors or delays and is provided “as is” — verify against your bank.

Read-only access

The OpenBudget MCP server is read-only — it cannot move money, place trades, or modify any account.

Third-party AI clients

Your prompts and the data returned are processed by your AI client (Claude, Hermes, OpenClaw, ChatGPT, Codex, Cursor) under its own terms. AI can be wrong — verify before acting.

Authorization

Connecting grants read access via OAuth; revoke it anytime from your client's settings. Use is governed by our Terms and Privacy Policy.