1. 服务概述
一句话简介：为你的 AI 助手提供对本地个人财务数据的类型化访问——无需将任何数据发送到机器之外
- 服务名称：tuskledger-mcp
- 版本号：v0
- 开发者/提供方：BradMorphsters
- 协议类型：MCP (Model Context Protocol)
2. 核心功能
该MCP服务提供的主要功能点：
- list_accounts— 每个连接账户的余额和同步状态
- query_transactions— 按日期、账户、类别等过滤交易
- search_transactions— 在商家和备注中进行模糊文本搜索
- get_spending_summary— 按类别汇总日期范围内的支出
- get_top_merchants— 查看支付最多的商家
- get_recurring_subscriptions— 获取订阅服务（Netflix、健身房等）
- get_upcoming_bills— 未来30天的账单和运行余额
- get_net_worth— 当前净值和12个月趋势
- get_holdings— 每个投资持仓详情
- get_investments_summary— 投资组合汇总和资产配置
- get_retirement_projection— 退休场景的蒙特卡洛模拟
- run_sync— 触发 Plaid 数据拉取
- list_stale_accounts— 数据过期的账户列表
3. 使用场景
该服务适合在以下情况下使用：
- 交易分类：将过去6个月的 Whole Foods 交易从"购物"改为"杂货"
- 支出查询：快速查询上季度咖啡支出，无需点击UI
- 净值诊断：分析净值下降的原因，查看账户、余额和近期交易
- HSA检查：检查当年HSA是否达到上限，计算差距
4. 接入方式
4.1 服务端点
本地后端地址：http://127.0.0.1:8000
所有数据都在本地处理，不经过互联网传输。
4.2 认证与权限
当前版本假设 Tusk Ledger 后端以DEV_BYPASS_AUTH=true模式运行。如果启用了认证，MCP 服务器的调用将返回 401 错误。
4.3 数据格式
通过本地 HTTP API 与 Tusk Ledger 后端通信，返回结构化的 JSON 数据。
4.4 服务器配置
在MCP客户端配置中添加服务（推荐使用 uvx）：
{ "mcpServers": { "tuskledger": { "command": "uvx", "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"], "env": { "TUSKLEDGER_BASE_URL": "http://127.0.0.1:8000", "TUSKLEDGER_TIMEOUT_SECONDS": "30" } } } }5. 接口定义
配置环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
TUSKLEDGER_BASE_URL | http://127.0.0.1:8000 | Tusk Ledger 后端监听地址 |
TUSKLEDGER_TIMEOUT_SECONDS | 10 | 每个请求的超时时间（秒） |
6. 快速开始
6.1 环境要求
- 运行中的 Tusk Ledger 主应用
- Python 3.10+
- 支持 MCP 的客户端（Claude Desktop、Cursor、Cowork、Claude Code 等）
6.2 安装方式
方式 A — uvx（推荐，无需永久安装）
pip install uv然后在 MCP 客户端配置中添加 uvx 命令。
方式 B — pip 安装
pip install git+https://github.com/BradMorphsters/tuskledger-mcp方式 C — 开发模式
git clone https://github.com/BradMorphsters/tuskledger-mcp cd tuskledger-mcp python -m venv .venv && source .venv/bin/activate pip install -e .7. 注意事项
- 只读设计：v0 版本是只读的，不暴露删除账户、交易、规则或目标的操作
- 安全考虑：不可逆的更改应在 Web UI 中进行，以便查看即将发生的操作
- 数据隐私：所有数据都在本地处理，不发送到
127.0.0.1之外的任何地方 - 故障排查：使用
./tuskledger doctor进行整体诊断 - 开源协议：MIT License
