tuskledger-mcp MCP 服务说明文档

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_AUTHtrue模式运行。如果启用了认证MCP 服务器的调用将返回 401 错误。4.3 数据格式通过本地 HTTP API 与 Tusk Ledger 后端通信返回结构化的 JSON 数据。4.4 服务器配置在MCP客户端配置中添加服务推荐使用 uvx{ mcpServers: { tuskledger: { command: uvx, args: [--from, githttps://github.com/BradMorphsters/tuskledger-mcp, tuskledger-mcp], env: { TUSKLEDGER_BASE_URL: http://127.0.0.1:8000, TUSKLEDGER_TIMEOUT_SECONDS: 30 } } } }5. 接口定义配置环境变量变量默认值说明TUSKLEDGER_BASE_URLhttp://127.0.0.1:8000Tusk Ledger 后端监听地址TUSKLEDGER_TIMEOUT_SECONDS10每个请求的超时时间秒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 githttps://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