avenir-mcp

本地服务

avenir-mcp.pages.dev金融数据41 天前更新

代码仓库访问官网

关于 avenir-mcp

avenir-mcp 是面向 YNAB 用户的非官方 MCP 服务，可让 AI Agent 查看预算并协助规划。默认只读；启用写入后，变更需确认且可撤销。

主要功能

01查看月度预算摘要
02预测余额与债务偿还计划
03搜索交易并建议分类
04对账账户
05预览、确认并撤销预算变更

适用场景

01查找当月超支类别
02估算余额是否会低于零
03检查待处理交易的分类
04在预算类别间转移资金并保留撤销选项

MCP 相关

向 MCP 客户端提供 YNAB 预算读取与规划工具。默认不注册写入工具；启用后，变更需确认，并可用 undo_operation 撤销。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "mathbeal-avenir": {
      "command": "uvx",
      "args": [
        "avenir-mcp"
      ],
      "env": {
        "YNAB_API_KEY": "<YNAB_API_KEY>",
        "AVENIR_MCP_WRITE": "<AVENIR_MCP_WRITE>"
      }
    }
  }
}

启动命令uvx avenir-mcp

需要配置的环境变量

YNAB_API_KEY密钥Your YNAB personal access token (YNAB > Account settings > Developer settings).

AVENIR_MCP_WRITESet to 1 to expose the write tools; read-only otherwise.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiavenir-mcp0.8.0stdio

工具

收录的工具列表 · 更新于 3 天前

参数	类型	必填	说明
until	string	是	预测截止月份，格式为 YYYY-MM，最多提前 24 个月。
plan_id	string	是	YNAB 计划 ID 或 'last-used'。
one_offs	any	否	预期的一次性金额：{date YYYY-MM-DD, amount, label}；不包括已在 YNAB 中安排的金额，此类金额会计入。
account_ids	any	否	要纳入的账户（来自 list_accounts）；默认包括所有未关闭的预算账户。
monthly_income	any	否	每月预期收入，替代从历史记录（定期或平均值）及 YNAB 计划交易中得出的收入；默认使用其显示值。
variable_monthly	any	否	除定期费用外的月度支出（负数）；默认值为过去 3 个月的平均值。

详细介绍

avenir-mcp：一款非官方的 YNAB MCP 服务

🇬🇧 avenir-mcp（avenir 在法语中意为“未来”）可让 AI Agent 读取你的 YNAB 计划，并帮助你规划接下来的安排。

🇫🇷 avenir-mcp 可让 AI Agent 读取你的 YNAB 计划，并帮助你规划接下来的安排。

用通俗的话向 Claude 或任何 MCP 客户端询问你的计划。默认只读；每项更改都会先预览、由你确认，并且可以撤销。

安装

你需要一个 YNAB 个人访问令牌：YNAB → 账户设置 → 开发者设置 → 新建令牌。

Claude Desktop，无需终端：将按钮下载的文件拖到 设置 → 扩展，然后在该页面粘贴你的令牌。

Claude Code，一条包含令牌的命令：

claude mcp add avenir-mcp --env YNAB_API_KEY=your-token -- uvx avenir-mcp

两种安装方式都采用只读模式。Cursor、LM Studio、VS Code、Windows、修改预算 (AVENIR_MCP_WRITE=1) 及所有选项：安装 · 配置。

一段 30 秒的对话。用户询问这个月的情况如何，以及房间还剩多少预算，Agent 同时调用四个只读工具：月度摘要、所有类别、预算与支出对比、三个月数据。它回答说，餐饮是唯一超出预算的类别：已支出 166.50，可用额度为 144.00（预算 120.00 + 之前月份结余 24.00），占 138.8%，可用额度为 −22.50；该类别过去三个月的支出从 113.70 → 119.90 → 166.50 逐月上升；网球还剩 80.00，杂货还剩 411.90。它提议用网球类别的 22.50 补足，该类别目前尚无支出。用户回答“从网球类别补。”，move_money 随后显示预览，不会产生任何更改：网球预算从 80.00 → 57.50，餐饮预算从 120.00 → 142.50，可用额度从 −22.50 → 0.00，正好达到预算；界面上有取消和确认按钮，并提醒用户确认前不会有任何更改，且任何更改都可以撤销。

▶ 观看 20 秒导览

演示预算中的 get_net_worth_trend：过去 18 个月里，尽管汽车贷款产生了利息，债务仍从 27,198 降至 19,041，资产不断增长，净资产从 −24,038 升至 +1,230；期间因汽车维修出现一次下跌，圣诞节时又出现一次下跌。

两张图都来自虚构的演示预算，由 python -m docsgen 重放：每个数字都与 avenir-mcp 今天给出的回答一致。

你可以询问什么

了解本月情况 — “本月哪个类别超支了？”→ get_monthly_summary
预测支出 — “到 12 月前我的余额会变成负数吗？”→ forecast_balance
还清债务 — “如果每月还 500，我的债务什么时候能还清？”→ get_debt_payoff_plan
整理交易 — “为待处理的交易分类。”→ suggest_categories，经你确认后应用
查找一笔交易 — “哪笔交易是 12 日那张 86.40 的收据？”→ find_transactions
对账 — “我的银行显示 3,440.80。YNAB 的金额一致吗？”→ reconcile_account
更改内容 — “从 Tennis 转 30 到 Restaurants。”→ move_money，操作会先预览、经你确认，并可通过 undo_operation 撤销

查看每个工具的实际回答：参考文档 · 使用案例。

找不到你想问的问题？有想法？ 请在 Discussions → Ideas 告诉我们你想询问预算的问题；如需了解如何使用 avenir-mcp，请前往 Discussions → Q&A。切勿发布真实金额、真实账户或你的令牌。

为什么选择 avenir-mcp

面向任务的工具，而非端点。 一个工具负责分类当月情况，另一个负责对账。
默认只读。 只有在你启用后，才会注册用于更改计划的工具。
预览、确认、撤销。 写入操作会等待你的确认；undo_operation 可以撤销操作。
提供 Agent 可读取的答案。 包含货币单位和类型化答案；银行文本会被视为不可信内容。
经过验证。 行覆盖率和分支覆盖率均为 100 %，并在虚构计划上由真实 Agent 测试：25/25。

询问本月预算情况后，Agent 使用两个只读工具读取当月数据并回答：有一个类别超出预算，Restaurants 超支 22.50，其余一切正常。

在演示计划上运行 forecast_balance：从本月至未来三个月的月末余额逐月上升；结果列出了每个月余额最低的日期，以及安排在下个月的一笔年度保险付款。

📖 文档：https://avenir-mcp.pages.dev/avenir-mcp/ · English · Français · Español · Deutsch · Nederlands

Claude Code 插件

plugin/ 是作为 Claude Code 插件运行的 avenir-mcp：Claude Code 会向你索取令牌，将其妥善隐藏，并从插件自身锁定的环境中启动服务。从克隆的仓库启动： claude --plugin-dir plugin。

插件	内容
运行	`uv run --locked --project` 插件文件夹，启动由 `plugin/pyproject.toml` 固定的发行版本，仅此而已。没有自带脚本、构建步骤、钩子或 shell
连接	首次运行时连接 `pypi.org` 和 `files.pythonhosted.org`，以安装该发行版本及 `plugin/uv.lock` 固定的版本；之后像 avenir-mcp 一贯的做法一样，携带你的令牌连接 `api.ynab.com`
写入	`uv` 在插件文件夹内解析的环境，以及 `uv` 自身的缓存。不会写入其他位置
对你的计划的更改	无。它以只读模式启动 avenir-mcp：未设置 `AVENIR_MCP_WRITE`，因此永远不会注册用于更改计划的工具

开发

git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcp
uv sync
just check        # lint, types, tests at 100 % coverage, vocabulary, lockfile
just docs-serve   # the documentation, live
just evaluate     # a real agent on the demo plan (uses your Claude plan)

提交拉取请求前，请阅读 AGENTS.md 和 CONTRIBUTING.md。安全问题报告：SECURITY.md。另请参阅：ARCHITECTURE.md、ROADMAP.md、GOVERNANCE.md 和行为准则。

基于 YNAB 的 API v1.87.0 构建并测试；每周运行的 YNAB API drift 检查会在 YNAB 发布新版本时失败。每次更改时都会依据 YNAB 于 2025-05-28 发布的 API 条款进行自检（命名、署名、YNAB 自有图片、仅供令牌所有者使用的个人令牌、每小时限额）；每周运行的任务会在条款更改时将该徽章标为红色。

隐私政策

avenir-mcp 是由你自行运行的程序，而非服务：其发布者不运行任何服务器，也不会收到你的任何数据。你的令牌从环境中读取，作为机密值保存在内存中，并且只会发送给 YNAB；工具需要时会获取你的计划数据并返回给你的 Agent，因此你的 MCP 客户端背后的模型提供商也能看到这些数据。关于处理哪些数据、保留多久以及如何删除： https://avenir-mcp.pages.dev/avenir-mcp/project/privacy/。

许可

MIT。

非官方项目

我们与 YNAB 或其任何子公司、关联公司均无关联、联系，也未获其官方认可。YNAB 官方网站地址为 https://www.ynab.com。YNAB 和 You Need A Budget 这些名称，以及相关名称、商号、标记、商标、徽章和图片，均为 YNAB 的注册商标。此处提及这些名称，仅为说明 avenir-mcp 所适配的服务。该项目已被 YNAB 列入其适配 YNAB目录中的第三方应用。未获 YNAB 背书。

avenir-mcp 仅供你在自己的设备上使用自己的 YNAB 令牌。不支持将其作为公开或共享服务运行。该软件按原样提供，不作任何保证，也不构成财务建议：你仍需对自己确认的更改负责。请参阅法律声明。

支持 Markdown

登录后评论