# Beancount.io

Connects your AI agent to a hosted Beancount ledger: BQL queries, reports, files and bank imports.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 313
- Author: bex-co
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/bex-co/beancount-io/tree/HEAD/backend-cluster/backend-v2
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/beancountio

## What it does

Beancount.io is an MCP server that gives an agent access to your hosted Beancount ledger. Through it you can run BQL queries, pull reports, work with files and trigger bank statement imports — all from the agent conversation, without switching to the web UI.

The server runs over HTTP and connects with a single command. For Claude that's `claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp`. Equivalent commands exist for Codex, Cursor, GitHub Copilot and Gemini CLI. Because the transport is HTTP, there's no separate process to start.

You need a personal access token, and those are available on paid plans. Create one in settings and hand it to the agent — without a token the server won't authorize ledger requests. The token is shown once, so keep it in a secret manager.

## Requirements
- Remote server: `https://beancount.io/api-gateway/mcp`

## Install

### Claude Code (native platform)

**Platform CLI: remote server**
```bash
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp
```

### Codex

**Platform CLI: remote server**
```bash
codex mcp add backend-v2 --url https://beancount.io/api-gateway/mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "backend-v2": {
            "url": "https://beancount.io/api-gateway/mcp"
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "backend-v2": {
            "type": "http",
            "url": "https://beancount.io/api-gateway/mcp"
        }
    }
}
```

### Gemini CLI

**Platform CLI: remote server**
```bash
gemini mcp add -t http backend-v2 https://beancount.io/api-gateway/mcp
```

## When to use it
- run a BQL query against the ledger from the agent chat
- pull a financial report without opening the web UI
- import a bank statement into the ledger
- view and edit ledger files through the agent
- reconcile ledger entries against bank transactions

## Example prompts
- Show all accounts with a non-zero balance this month
- Import the statement from `statement.csv` into the ledger
- Reconcile the latest transactions against the bank statement

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [CCXT](https://affpapa.org/en/nevibecode/mcp/ccxt.md) — MCP server · ★ 44583
- [Finance Toolkit](https://affpapa.org/en/nevibecode/mcp/finance-toolkit.md) — MCP server · ★ 5458
- [EdgarTools](https://affpapa.org/en/nevibecode/mcp/edgartools.md) — MCP server · ★ 2814
- [LetsFG — Flights & Hotels](https://affpapa.org/en/nevibecode/mcp/letsfg-flights-hotels.md) — MCP server · ★ 2188
- [AutoTS](https://affpapa.org/en/nevibecode/mcp/autots.md) — MCP server · ★ 1434

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md