mcp帐户
只读MCP服务器，为AI代理提供结构化访问权限 Beancount 个人财务分类账。
______________________________________________________________________
先决条件
- Python 3.12+
- 紫外线 包管理器
______________________________________________________________________
安装
uv sync______________________________________________________________________
配置
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
BEANCOUNT_FILE | ✅ | — | 通往你的绝对之路 .beancount 分类帐档案 |
ACCOUNT_ALLOWLIST | ❌ | （无） | 逗号分隔的帐户前缀白名单（例如。 Assets:Bank,Expenses:) |
BEANCOUNT_RELOAD | ❌ | false | 在每次工具调用时重新加载分类账（开发模式） |
BASE_CURRENCY | ❌ | operating_currency 从分类账 | 覆盖基础货币 net_worth_converted （例如。 CHF) |
复制 .env.example 到 .env 并填写您的值：
cp .env.example .env______________________________________________________________________
跑步
BEANCOUNT_FILE=/path/to/ledger.beancount uv run mcp-beancount或者用a .env 文件（需要 dotenv 或同等）：
export BEANCOUNT_FILE=/path/to/ledger.beancount
uv run mcp-beancount______________________________________________________________________
MCP客户端配置
克劳德桌面
添加 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"beancount": {
"command": "uv",
"args": ["run", "--project", "/path/to/mcp-beancount", "mcp-beancount"],
"env": {
"BEANCOUNT_FILE": "/absolute/path/to/ledger.beancount",
"ACCOUNT_ALLOWLIST": ""
}
}
}
}开爪
添加到您的OpenClaw MCP配置中：
{
"mcpServers": {
"beancount": {
"command": "uv",
"args": ["run", "--project", "/path/to/mcp-beancount", "mcp-beancount"],
"env": {
"BEANCOUNT_FILE": "/absolute/path/to/ledger.beancount"
}
}
}
}______________________________________________________________________
工具参考
| 工具 | 签名 | 描述 |
|---|---|---|
get_net_worth | (date?: str) | 截至日期的净值（资产-负债），多币种，价格转换 |
get_balances | (account_pattern: str) | 与账户前缀/glob匹配的非零余额 |
get_income_statement | (year: int, month?: int) | 一段时间的收入与支出 |
get_transactions | (account?: str, since?: str, limit?: int) | 最近的交易，可过滤 |
query | (bql: str) | 原始BQL查询（只读） |
例子
# Net worth today (multi-currency, per-currency breakdown + converted total)
get_net_worth()
# Returns:
# {
# "as_of": "2026-03-28",
# "base_currency": "CHF",
# "assets": {
# "Assets:Bank:UBS": {"CHF": 50000.0},
# "Assets:Broker:IBKR": {"USD": 30000.0}
# },
# "liabilities": {
# "Liabilities:CreditCard": {"CHF": -2000.0}
# },
# "total_assets": {"CHF": 50000.0, "USD": 30000.0},
# "total_liabilities": {"CHF": -2000.0},
# "net_worth": {"CHF": 48000.0, "USD": 30000.0},
# "net_worth_converted": 74700.0, # CHF 48000 + USD 30000 * 0.89
# "skipped_positions": [] # currencies with no price directive
# }
# Net worth as of 2025-12-31
get_net_worth(date="2025-12-31")
# All bank account balances
get_balances(account_pattern="Assets:Bank:")
# 2026 income statement
get_income_statement(year=2026)
# Q1 2026 income statement
get_income_statement(year=2026, month=1)
# Last 20 food expenses
get_transactions(account="Expenses:Food", limit=20)
# Transactions since 2026-01-01
get_transactions(since="2026-01-01")
# Raw BQL query
query("SELECT account, sum(position) WHERE account ~ 'Assets' GROUP BY account")______________________________________________________________________
运行测试
BEANCOUNT_FILE=/path/to/any.beancount uv run pytest或使用包含的 sample.beancount （测试通过夹具自动使用此功能）：
uv run pytest______________________________________________________________________
安全
- 没有写：beancount库本质上是只读的
- 没有shell调用：所有计算都是通过beancount Python API进行的
- 路径隔离:
BEANCOUNT_FILE在启动时设置；从未通过工具论证暴露 - 允许名单：可选
ACCOUNT_ALLOWLIST将所有工具限制为特定的帐户前缀