# Beancount.io MCP server
> Query, edit and reconcile a hosted Beancount ledger with BQL, reports, files and bank imports.
- Listing: https://mcp.tc/i/beancount-io
- Connect: use the server's own URL `https://beancount.io/api-gateway/mcp` (OAuth sign-in at the server); clients connect to it directly. The listing link is a page, not an MCP endpoint.
- Type: remote (Streamable HTTP)
- Auth: OAuth sign-in
- Category: [Finance & Payments](https://mcp.tc/c/finance-payments)
- Vendor: bex-co
- Homepage:
- Repository:
## About
Connects an AI assistant to a hosted Beancount.io plain-text double-entry ledger. It can run BQL queries, produce reports, edit ledger files and reconcile accounts with bank imports.
The server runs as a hosted streamable HTTP endpoint at beancount.io/api-gateway/mcp. Users sign in with OAuth, and the scopes cover ledger read, write and admin access. A Beancount.io account is required. Self-hosted deployments expose the same path on their own host.
## What it can do
- Run BQL queries against a hosted ledger
- Generate reports such as balance sheet and income statement
- Edit ledger files and record transactions
- Reconcile accounts and import bank data
## Example prompts
- "Show my balance sheet as of today from my Beancount ledger."
- "Run a BQL query for total dining expenses this year."
- "Record a 12.50 coffee expense paid from Assets:Checking."
- "Import this bank statement and reconcile my checking account."
## Install
### Claude Code
1. Run this in a terminal, in your project folder:
```bash
claude mcp add --transport http beancount-io https://beancount.io/api-gateway/mcp
```
2. Start Claude Code, type `/mcp`, pick **beancount-io** and choose **Authenticate**. A browser window opens for the bex-co sign-in.
Add `--scope user` to make it available in every project, not just this one.
### Claude Desktop
1. Open **Customize → Connectors**, click **+ Add**, then **Add custom connector**.
2. Name it **Beancount.io** and paste this URL:
```url
https://beancount.io/api-gateway/mcp
```
3. Click **Add**, then **Connect**, and sign in when bex-co asks.
Claude Desktop’s JSON config file only starts local servers. Remote servers go through Connectors, and connectors you add on claude.ai show up here too.
### claude.ai
1. Open the connector form on claude.ai. This button fills in the name and URL for you:
[Add to claude.ai]() (opens connector settings)
2. Check that the URL reads `https://beancount.io/api-gateway/mcp` and click **Add**.
3. Click **Connect** and sign in when bex-co asks.
Free plans allow one custom connector. On Team and Enterprise plans an owner adds it under **Organization settings → Connectors**.
### ChatGPT
1. On chatgpt.com, go to **Plugins**, select **+**, then **Add custom MCP server**.
2. Enter a name for the server.
3. Under **Connection**, paste `https://beancount.io/api-gateway/mcp` as the server URL, then for authentication choose **OAuth**. ChatGPT sends you to bex-co to sign in.
4. Check **I understand and want to continue**, then select **Create as a plugin**.
Whether you can add a custom MCP server depends on your ChatGPT plan and your workspace permissions (in Business workspaces, admins and owners can).
### Cursor
[Add to Cursor]() (opens Cursor)
Or add it by hand to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (this project):
`mcp.json`:
```json
{
"mcpServers": {
"beancount-io": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}
```
Cursor shows **Needs authentication** next to the server. Click the button beside it to sign in.
### VS Code
[Install in VS Code]() (opens VS Code)
Or from a terminal:
```bash
code --add-mcp '{"name":"beancount-io","type":"http","url":"https://beancount.io/api-gateway/mcp"}'
```
Or commit it to the repo in `.vscode/mcp.json`:
`.vscode/mcp.json`:
```json
{
"servers": {
"beancount-io": {
"type": "http",
"url": "https://beancount.io/api-gateway/mcp"
}
}
}
```
VS Code asks you to sign in the first time the server starts.
### Devin Desktop
1. Add it to `~/.config/devin/mcp_config.json` (macOS and Linux) or `%APPDATA%\devin\mcp_config.json` (Windows):
`mcp_config.json`:
```json
{
"mcpServers": {
"beancount-io": {
"serverUrl": "https://beancount.io/api-gateway/mcp"
}
}
}
```
2. Refresh the MCP server list in Cascade and sign in when asked.
Devin Desktop is the new name for Windsurf. It reads `serverUrl` (or `url`) for remote servers.
### Codex
```bash
codex mcp add beancount-io --url https://beancount.io/api-gateway/mcp
codex mcp login beancount-io
```
Or edit `~/.codex/config.toml` directly:
`config.toml`:
```toml
[mcp_servers.beancount-io]
url = "https://beancount.io/api-gateway/mcp"
```
### Gemini CLI
```bash
gemini mcp add --transport http beancount-io https://beancount.io/api-gateway/mcp
```
Then, inside Gemini CLI, run `/mcp auth beancount-io` to sign in.
This adds it to the current project. Add `-s user` to use it everywhere.
### Any client
Most clients accept this shape. Some name the URL field differently: `serverUrl` in Devin Desktop, `httpUrl` in Gemini CLI’s settings file.
```json
{
"mcpServers": {
"beancount-io": {
"type": "http",
"url": "https://beancount.io/api-gateway/mcp"
}
}
}
```
Zed puts servers under `context_servers` in its settings. Cline needs `"type": "streamableHttp"`, or it assumes SSE.
Client only starts local servers? Bridge it with `npx -y mcp-remote https://beancount.io/api-gateway/mcp`.
## Details
- Server version: 1.0.0
- Last checked: 2026-11-15 (reachable, asks for credentials)
- Listed: 2026-11-01
- Updated: 2026-11-01
---
Source: https://mcp.tc/i/beancount-io (mcp.tc is an independent directory, not affiliated with this server's publisher). Corrections: https://mcp.tc/report