marmot-ledger-mcp

简体中文 · English below

Marmot Ledger 的 MCP（Model Context Protocol）服务器，让 AI Agent（Claude Code / Claude Desktop / Cursor 等）能够通过自然语言完成账单录入、查询和报表生成。

特性

• HTTP API 客户端 — 通过 REST API 连接 Marmot Ledger 后端，不直接连数据库；MCP 进程和后端可分离部署。
• 交互式登录 + token 持久化 — 会话内通过 login tool 输入账号密码；token 缓存到 ~/.marmot/mcp-session.json（0600 权限），下次启动自动恢复。
• 自动 token 刷新 — 快过期时（100s 缓冲）自动续期；并发请求去重。
• 多用户切换 — 会话内 logout + login 即可切换账号，无需重启进程或改配置。
• stdio 传输 — 与 Claude Code / Claude Desktop / Cursor 无缝集成。
• 25 个 MCP Tools — 覆盖认证、参考数据、记录 CRUD、查询、报表、家庭。
• 4 个 MCP Prompts — record_expense / record_income / monthly_report / net_worth_check。
• 多币种原生支持 — 查询结果按原始币种分组，不做本位币折算。

快速开始

前置条件

• Node.js ≥ 18
• 一个可访问的 Marmot Ledger 后端（项目主页）

集成到 Claude Code

claude mcp add --scope user marmot-ledger \
  -e MARMOT_API_URL=http://localhost:7070 \
  -- npx -y marmot-ledger-mcp

启动时不带凭据。在会话里说"登录 marmot"或"我今天午餐花了 35 块微信支付"，Claude 会自动调用 login tool 向你询问账号密码。登录一次后 token 会持久化，下次直接可用。

集成到 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "marmot-ledger": {
      "command": "npx",
      "args": ["-y", "marmot-ledger-mcp"],
      "env": {
        "MARMOT_API_URL": "http://localhost:7070"
      }
    }
  }
}

保存后重启 Claude Desktop 即可看到 marmot-ledger tools 出现在工具箱里。

配置

三种方式，优先级 环境变量 > 配置文件 > 交互式 login：

1. 只配 API 地址（推荐，最安全）

MCP 启动时不带账号密码，用户在会话里通过 login tool 交互登录。密码只在进程内存中活着，登出后清除；持久化的只有服务器颁发的 token。

2. 环境变量（无人值守场景）

export MARMOT_API_URL=https://your-api.example.com
export MARMOT_ACCOUNT=your_account
export MARMOT_PASSWORD=your_password

3. 配置文件 ~/.marmot/mcp-config.json

{
  "apiUrl": "https://your-api.example.com",
  "account": "your_account",
  "password": "your_password"
}

切换账号

你：退出登录，换成 zhang3
Agent：（调 logout + login({account:"zhang3", password:"..."})）
       ✅ 已登录：zhang3
你：这个月我花了多少？
Agent：（get_summary）...

Tool 清单

认证

| Tool | 用途 | |------|------| | login | 用账号密码登录，切换账号也用这个 | | logout | 清除当前会话（包括持久化 token） | | whoami | 查看当前登录账号 |

参考数据

| Tool | 用途 | |------|------| | list_categories | 收支分类 | | list_buckets | 资金桶 | | list_channels | 收付款渠道 | | list_accounts | 账户 |

记录 CRUD

| Tool | 用途 | |------|------| | create_record | 创建 18 种场景之一 | | update_record | 修改（rollback-and-rebuild） | | delete_record | 删除（自动回滚余额） |

查询

| Tool | 用途 | |------|------| | list_records | 分页查询，支持时间/币种/分类/渠道/关键词筛选 | | get_record_detail | 单条完整详情含 ledger entries | | get_outstanding | 未结清应收/押金/借出 |

报表

| Tool | 用途 | |------|------| | get_summary | 收支汇总（按币种） | | get_category_breakdown | 按 CategoryGroup 分布 | | get_trend | 收支趋势 | | get_net_worth_trend | 净资产趋势 | | get_investment_summary | 投资汇总 |

家庭

| Tool | 用途 | |------|------| | list_families | 用户所属家庭 | | list_family_members | 成员列表 | | get_family_summary | 家庭收支汇总 | | get_family_category_breakdown | 家庭分类分布 | | get_family_trend | 家庭收支趋势 | | get_family_net_worth_trend | 家庭净资产趋势 | | get_family_assets | 家庭资产明细 |

Prompts

Prompts 是打包好的多步对话模板，可以在 Claude Desktop 的 / 命令菜单里直接调用：

| Prompt | 用途 | |--------|------| | record_expense | 引导 Agent 完成一笔支出记录 | | record_income | 引导 Agent 完成一笔收入记录 | | monthly_report | 综合多个 report tool 生成本月账单报告 | | net_worth_check | 净资产体检 + 投资汇总 |

领域模型速览

• financial_event — 财务事件（发生了什么）
• ledger_entry — 余额分录（哪些 Bucket 余额变化）
• bucket — 资产/负债/虚拟资金池（保存余额）
• account — 平台/机构分组（不保存余额）

支持的 18 种事件场景：

income / expense / transfer / refund / exchange
receivable_create / receivable_collect
deposit_create / deposit_refund
loan_out / loan_collect
investment_buy / investment_sell / investment_income / investment_revalue
balance_adjustment

统计口径：

• income / expense 进入普通收支统计
• refund 作为支出抵扣
• 其他事件默认不进入普通收支统计
• 多币种分块展示，不做本位币折算

安全说明

• 密码只在进程内存中保存，logout 或进程退出后清除。
• 持久化的会话文件 ~/.marmot/mcp-session.json 权限 0600（仅当前用户可读），仅保存服务器颁发的 token，不含密码。
• 会话按 apiUrl 隔离——切服务器不会误用旧 token。
• 建议 Marmot 后端启用 HTTPS。
• 不要把 MARMOT_PASSWORD 提交到 git 或分享给他人。

开发

git clone https://github.com/here-tunan/marmot-ledger.git
cd marmot-ledger/mcp
npm install
npm run typecheck    # tsc --noEmit
npm run build        # 打包到 dist/
npm run smoke        # 端到端 tools smoke test（需要有效凭据）
npm run smoke:auth   # 登录 / 登出 / 切换 smoke test

许可

Apache-2.0，见 LICENSE。

marmot-ledger-mcp (English)

An MCP (Model Context Protocol) server for Marmot Ledger. Lets AI agents (Claude Code / Claude Desktop / Cursor) create records, query transactions, and generate reports through natural language.

Features

• HTTP API client — connects to the Marmot Ledger REST backend; the MCP process and the backend can run on separate machines.
• Interactive login + token persistence — sign in via the login tool inside your session; token is cached at ~/.marmot/mcp-session.json (mode 0600) and auto-restored on the next start.
• Automatic token refresh — refreshes ~100s before expiry; concurrent requests are deduplicated.
• Multi-user switch — swap accounts inside a session with logout + login; no restart or config edit.
• stdio transport — plug-and-play with Claude Code / Desktop / Cursor.
• 25 MCP tools — auth, reference data, record CRUD, queries, reports, family.
• 4 MCP prompts — record_expense / record_income / monthly_report / net_worth_check.
• Multi-currency native — results are grouped by original currency; no forced base-currency conversion.

Quick start

Prerequisites: Node.js ≥ 18 and a reachable Marmot Ledger backend.

Claude Code

claude mcp add --scope user marmot-ledger \
  -e MARMOT_API_URL=http://localhost:7070 \
  -- npx -y marmot-ledger-mcp

Then in a Claude Code session, just say what you want ("log a 35 CNY lunch, paid by WeChat"). Claude will call the login tool to prompt for your account and password on the first run. Token is cached; subsequent sessions skip login.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and add:

{
  "mcpServers": {
    "marmot-ledger": {
      "command": "npx",
      "args": ["-y", "marmot-ledger-mcp"],
      "env": {
        "MARMOT_API_URL": "http://localhost:7070"
      }
    }
  }
}

Restart Claude Desktop.

Configuration

Precedence: env vars > config file > interactive login.

1. API URL only (recommended, safest)

Start MCP without credentials; users log in via the login tool. The password only lives in process memory; only the token is persisted.

2. Environment variables (headless)

export MARMOT_API_URL=https://your-api.example.com
export MARMOT_ACCOUNT=your_account
export MARMOT_PASSWORD=your_password

3. Config file ~/.marmot/mcp-config.json

{
  "apiUrl": "https://your-api.example.com",
  "account": "your_account",
  "password": "your_password"
}

Switching accounts

You:    log out and switch to zhang3
Agent:  (calls logout + login({account:"zhang3", password:"..."}))
        ✅ signed in as zhang3
You:    how much did I spend this month?
Agent:  (get_summary) ...

Tools

See the Chinese section above for the full 25-tool table. Categories:

• Auth — login / logout / whoami
• Reference — list_categories / list_buckets / list_channels / list_accounts
• Record CRUD — create_record / update_record / delete_record
• Query — list_records / get_record_detail / get_outstanding
• Report — get_summary / get_category_breakdown / get_trend / get_net_worth_trend / get_investment_summary
• Family — list_families / list_family_members / get_family_summary / get_family_category_breakdown / get_family_trend / get_family_net_worth_trend / get_family_assets

Domain model recap

• financial_event — what happened
• ledger_entry — how bucket balances changed
• bucket — asset/liability/funds container that stores balance
• account — platform/institution grouping (no balance)

Ordinary reporting stays in the original currency; refunds offset expense instead of counting as income; transfer / exchange / receivable / deposit / loan / investment / balance-adjustment events do not enter ordinary income/expense stats by default.

Security notes

• The password only lives in process memory, wiped on logout or process exit.
• The persisted session file is 0600 and contains only the server-issued token.
• Sessions are keyed by apiUrl; switching servers doesn't reuse an old token.
• Prefer HTTPS for your Marmot backend.
• Do not commit MARMOT_PASSWORD to git or share it.

Development

git clone https://github.com/here-tunan/marmot-ledger.git
cd marmot-ledger/mcp
npm install
npm run typecheck
npm run build
npm run smoke        # end-to-end tools smoke test
npm run smoke:auth   # login / logout / switch smoke test

License

Apache-2.0. See LICENSE.