BilanceHelp CentreDownload
Connect Claude, ChatGPT or another AI app to BilanceAll articles

Getting started

Connect Claude, ChatGPT or another AI app to Bilance

Mihkel Vetemaa

Updated View as Markdown

Jump to

Connect Bilance to Claude, ChatGPT or another AI app, then ask it about your money.

You need an active Bilance subscription (a free trial counts) and the Bilance account you want to connect.

Your AI app must support custom MCP connectors. Some offer them only on paid plans.

Choose your AI app

ClaudeChatGPTGeminiCursorVS CodeOther AI app

Connect Claude

On a computer

  1. Open claude.ai in your browser or the Claude desktop app. Once added, Bilance works in the Claude phone app too.

  2. Open Customize 1 → Connectors 2 → Add 3 → Add custom connector 4.

    Claude desktop app: 1 points to Customize in the sidebar, 2 to the Connectors tab, 3 to the Add button and 4 to Add custom connector in its menu.

  3. Name it Bilance, paste the URL, then click Continue.

    https://mcp.bilanceapp.com/mcp
    The Claude desktop app with the Add custom connector dialog open: hands point to the name Bilance, the URL https://mcp.bilanceapp.com/mcp and Continue.

  4. Claude then shows more options. Leave them as they are and click Add.

    Claude's second Add custom connector screen with Authentication, OAuth client, Request headers and Advanced options, and a hand on the Add button.

  5. On the Bilance connector page, click Connect.

  6. Sign in to Bilance with Google, Apple or email.

  7. You should now see Bilance's tools listed.

  8. In a chat, ask about your money.

Using Claude Code in the terminal? Paste this prompt instead

Paste this into Claude Code

Read bilanceapp.com/mcp and connect Bilance MCP

Claude Code adds Bilance and opens the Bilance sign-in in your browser. Sign in there, then start a new session.

Or run it yourself:

claude mcp add --transport http --scope user bilance https://mcp.bilanceapp.com/mcp

Then type /mcp in Claude Code, select bilance and then Authenticate.

On your phone

  1. Open the Claude app on your phone.

  2. Open the menu and tap your profile.

    Claude phone app menu with a hand tapping the profile picture at the bottom left.

  3. Tap Connectors.

    Claude phone app settings with a hand tapping Connectors.

  4. Tap +, then Add custom connector.

    The Claude phone app menu with Browse connectors and Add custom connector, and a hand tapping Add custom connector.

  5. Name it Bilance, paste this URL, then tap Continue.

    https://mcp.bilanceapp.com/mcp
    The Claude phone app form: hands point to the name Bilance, the URL https://mcp.bilanceapp.com/mcp and Continue.

  6. Leave the defaults and tap Add.

  7. Sign in to Bilance with Google, Apple or email. The sign-in opens by itself.

  8. Bilance now shows in Connectors with its tools.

  9. In a chat, ask about your money.

Connect ChatGPT

On a computer

  1. Open chatgpt.com in your browser or the ChatGPT desktop app.

  2. Click the plug icon in the left bar 1, then Plugins 2 → Add 3 → Add custom MCP server 4.

    ChatGPT desktop app: 1 points to the plug icon in the left bar, 2 to Plugins, 3 to the Add button and 4 to Add custom MCP server in its menu.

  3. Name it Bilance and paste the URL. Tick I understand and want to continue, then click Create as a plugin.

    https://mcp.bilanceapp.com/mcp
    The ChatGPT desktop app with the Add custom MCP server form open: hands point to the name Bilance, the URL https://mcp.bilanceapp.com/mcp, the ticked I understand and want to continue, and Create as a plugin. Authentication is set to OAuth.

  4. Click Connect, then Continue to Bilance. Sign in and click Allow access.

  5. In a chat, type @Bilance and ask about your money.

Using Codex in the terminal? Paste this prompt instead

Paste this into Codex

Read bilanceapp.com/mcp and connect Bilance MCP

Codex adds Bilance and opens the Bilance sign-in in your browser. If the sign-in doesn't open, run codex mcp login bilance in your terminal.

On your phone

Don't see the Add custom MCP server option?

ChatGPT doesn't offer it to every account on the phone yet. If it's missing, connect on a computer instead. Bilance then works in the ChatGPT app too.

  1. Open chatgpt.com in Safari, not in the ChatGPT app. Once connected, Bilance works in both.

    The ChatGPT app icon crossed out, next to the Safari icon with a hand tapping it.

  2. Tap the sidebar button at the top left.

    chatgpt.com in Safari on a phone with a hand tapping the sidebar button at the top left.

  3. Tap the Plugins icon (the plug) in the sidebar.

    The chatgpt.com sidebar with a hand tapping the plug icon for Plugins.

  4. Tap + at the top right, then Add custom MCP server.

    The Plugins page on chatgpt.com with the + menu open and a hand tapping Add custom MCP server.
Don't see the Add custom MCP server option?

ChatGPT doesn't offer it to every account on the phone yet. If it's missing, connect on a computer instead. Bilance then works in the ChatGPT app too.

  1. Name it Bilance and paste this server URL.

    https://mcp.bilanceapp.com/mcp
    The Add custom MCP server form on a phone: hands point to the name Bilance and the server URL https://mcp.bilanceapp.com/mcp. Authentication is set to OAuth.

    Optional: download the Bilance icon

  2. Tick I understand and want to continue, then tap Create as a plugin.

    The bottom of the form: hands point to the ticked I understand and want to continue and to Create as a plugin.

  3. Tap Connect, then Continue to Bilance. Sign in and tap Allow access.

  4. Bilance now works in the ChatGPT app too.

Connect Gemini

  1. Open gemini.google.com in your browser.

  2. Click Customize 1 → Connectors 2 → + Custom 3.

    Gemini on gemini.google.com: 1 points to Customize in the sidebar, 2 to the Connectors tab and 3 to the + Custom button.
Don't see the + Custom button?

Gemini doesn't offer custom connectors to every account yet. If it's missing, use Claude or ChatGPT instead.

  1. Paste the URL and click Next.

    https://mcp.bilanceapp.com/mcp
    The Connect to an MCP server dialog in Gemini with https://mcp.bilanceapp.com/mcp in the MCP Server URL field, and hands pointing to the field and to Next.

  2. Sign in to Bilance and click Allow access.

  3. In a chat, ask about your money.

Connect Cursor

Add to Cursor

  1. Cursor opens and asks to install Bilance. Click Install.

  2. When Cursor asks, sign in to Bilance in your browser.

Add it by hand

Add this to ~/.cursor/mcp.json. Keep any servers already there.

{ "mcpServers": { "bilance": { "url": "https://mcp.bilanceapp.com/mcp" } } }

Then find bilance in the MCP list in Cursor Settings and sign in.

Connect VS Code

Add to VS Code

  1. VS Code opens the Bilance server page. Click Install.

  2. When VS Code asks, sign in to Bilance in your browser.

  3. Ask Copilot Chat about your money.

Connect another AI app

Add Bilance as a remote MCP server. It signs in with your Bilance account.

https://mcp.bilanceapp.com/mcp

Using an AI agent?

Paste this into it

Read bilanceapp.com/mcp and connect Bilance MCP

About connected AI apps

What the AI app can read

The same data you see in Bilance: accounts and balances, transactions with categories, tags and notes, spending and income summaries, reports, budgets, recurring payments, net worth and assets. If you use Shared Finances, it follows the household filter you picked in the app. Transactions on hidden accounts are left out.

What the AI app can change

When you ask, it can edit, add and delete transactions, categories, tags, budgets, recurring payments, manual accounts and assets, and refresh your bank data. On a transaction your partner shares with you, it can only change the category, exclude it, star it or mark it as seen.

Bilance applies a change as soon as the AI app sends it. Your AI app may ask you to approve it first.

To keep an AI app read-only, open Connected AI apps in Bilance, find the app and switch off Allow changes to your data.

Bilance never moves money. It can’t make payments or transfers from your bank, and neither can an AI app connected to it. A “payment” the AI app creates is a record in Bilance only.

Limits
Limit Allowance
Requests per day 300, shared by all your connected AI apps. One question can take several.
Requests per minute 60
Bank data refresh 1 a day. It only runs when some of your bank data is more than 6 hours old.
Transaction exports Pages of 500 rows, plus up to 3 larger pages a day

Daily limits reset at midnight UTC. When you reach a limit, the AI app gets a message with the time it resets. Requests refused because of a missing subscription don’t count.

Privacy

You sign in with your Bilance account in your browser. The AI app never sees your Bilance password or your bank login.

Your Bilance data stays where it is. When you ask a question, the AI app receives the answer and stores and processes it under its own terms and privacy policy, which may be outside the EEA. Only connect AI apps you trust. Disconnecting stops future access but doesn’t delete what the AI app already received or your chats there. See our privacy policy.

See or disconnect your AI apps

In the Bilance app, open the Account tab → Settings → Connected AI apps. It’s in the Privacy section. If you don’t see it there, no AI app is connected yet.

Each app shows when it last used your data. For each app you can switch off changes or bank data refresh, or Disconnect it.

Disconnecting stops the app’s access right away. A request already running may still finish. Some AI apps create a new connection every time you sign in, so the same app can appear more than once. Disconnect the ones you don’t use; “Last used” shows which one is active.

Things to try
  • “What did I spend on groceries last month, and how does that compare with the month before?”
  • “Which subscriptions renew this week?”
  • “Find all my Bolt rides and tag them as Transport.”
App-specific notes

Claude approval prompts: Claude asks before it uses each Bilance tool. To skip that, set Read-only tools to Always allow.

Claude Team or Enterprise: an admin adds the connector.

Gemini: not every Gemini account can add custom connectors yet, and it only works on gemini.google.com on a computer.

Troubleshooting

Subscription required

If you see “An active Bilance subscription is required”, subscribe or restore your purchases in Bilance, then ask again.

Sign-in keeps looping or fails

If sign-in loops back to the same page, use a normal browser window (not private mode) and allow cookies for mcp.bilanceapp.com.

If sign-in fails with “server_error”, sign in once more in the browser window that opens.

Wrong Bilance account

Check “Logged in as …” on the consent screen, or ask your AI app which Bilance account it’s connected to.

Disconnect the app in Bilance, then connect again with the right account.

You've reached a limit

If you see “Do not retry before …”, wait until the time shown, then ask again.

Changes are turned off

If you see “Changing Bilance data from this app is turned off”, open Connected AI apps in Bilance, find that app and switch on Allow changes to your data.

Connection was disconnected

If you see “This connection was disconnected”, connect the AI app to Bilance again.

Bilance can't load your data

If you see “Bilance data service is temporarily unavailable”, try again in a minute. If it keeps happening, email us.

If you see “Bilance had an internal error (reference mcp-…)”, the problem is on our side. Reconnecting won’t help. Email us the reference.

Numbers differ from Bilance

Amounts are converted to your default currency, and excluded transactions stay excluded. Check that the household filter matches the one in Bilance.

Changes you make in the app can take up to 30 seconds to show.

Still need help?

Email help@bilanceapp.com with your Bilance account email, the AI app you used and the exact message you saw.

Contact support
Was this helpful?
For AI agents

Read https://www.bilanceapp.com/mcp.md before you run anything, and follow it. It covers removal and errors too. In short:

  • Check first with claude mcp list or codex mcp list. If a bilance or plugin:bilance:bilance entry already uses https://mcp.bilanceapp.com/mcp, don’t add another. Sign in to that one, using the name claude mcp list shows.
  • Add: claude mcp add --transport http --scope user bilance https://mcp.bilanceapp.com/mcp or codex mcp add bilance --url https://mcp.bilanceapp.com/mcp.
  • Run the sign-in yourself with claude mcp login bilance or codex mcp login bilance. For the plugin, use claude mcp login plugin:bilance:bilance. The user only approves in the browser. claude mcp login needs a terminal. From a shell without one, run script -q /dev/null claude mcp login bilance (macOS; for the plugin, script -q /dev/null claude mcp login plugin:bilance:bilance) in the background. Wait until the command finishes before you reply.
  • If the sign-in fails with server_error, run it once more.
  • Verify: call get_finance_context and tell the user "Connected to Bilance as <email>". Tools load when a session starts. In Claude Code you can check from the current session with claude -p "Call get_finance_context and tell me connectedAccount.email" --allowedTools mcp__bilance__get_finance_context (for the plugin: mcp__plugin_bilance_bilance__get_finance_context).
← PreviousAI Chat: ask anything about your own money

New to Bilance?

Connect your banks and let the app do the categorizing — set up in about 2 minutes.

Get the app