AI导哈

YNAB预算分析服务器

一个基于模型上下文协议（MCP）的YNAB预算分析服务器，通过自然语言交互提供预算分析、支出模式检测和个性化财务建议。

  • by auzroz
  • TypeScript
  • 混合部署
  • 4 星标
  • 更新于
在 GitHub 查看 auzroz/ynab-mcp

使用说明

YNAB MCP服务器

全面 模型上下文协议（MCP） 服务器 YNAB（你需要预算） 这使得AI助手能够 克劳德桌面版 阅读你的预算，分析支出模式，检测订阅，并提供个性化的财务见解——所有这些都是通过自然对话实现的。

为什么选择YNAB MCP？

传统的YNAB集成需要手动调用API或自定义脚本。此MCP服务器允许您：

  • 自然地讨论你的预算 --问克劳德“我在外出就餐上超支了吗？”并立即获得见解
  • 获取基于人工智能的财务分析 --订阅检测、支出趋势、节省建议和预算健康评分
  • 默认情况下保持安全 --只读模式可防止意外更改
  • 访问所有内容 -共66个工具：YNAB API全面覆盖（40个工具）、23个自定义分析工具和3个系统工具

特性

特性 描述
广泛的API覆盖范围 66个MCP工具，跨越YNAB API端点
高级分析 23种用于支出分析、趋势检测和财务洞察的工具
默认情况下为只读 写入操作需要明确的选择加入(YNAB_READ_ONLY=false)
智能速率限制 令牌桶算法，每小时180个请求（10%安全裕度）
智能高速缓存 减少对不经常更改的数据的API调用
类型安全 带有Zod模式验证的完整TypeScript实现

快速开始

先决条件

安装选项

选项1:npx（最简单）

无需安装--直接运行：

npx ynab-mcp

选项2:Docker

docker run -e YNAB_ACCESS_TOKEN=your_token ghcr.io/auzroz/ynab-mcp:latest

选项3：从源代码安装

# Clone the repository
git clone https://github.com/auzroz/ynab-mcp.git
cd ynab-mcp

# Install dependencies and build
npm install
npm run build

# Run the server
npm start

配置

服务器是通过环境变量配置的：

变量 必填 描述
YNAB_ACCESS_TOKEN 是 您的YNAB个人访问令牌
YNAB_BUDGET_ID 否 默认预算UUID（如果未设置，则使用“上次使用”）
YNAB_READ_ONLY 否 设置为 false 启用写入操作（默认值： true)

远程/HTTP模式

默认情况下，服务器会说话 标准 （当地）。集 MCP_TRANSPORT=http 运行它 作为 远程 服务器通过MCP流式HTTP传输 POST /mcp，与a 朴素 GET /health 用于负载均衡器。每个会话都有一个隔离 客户端/缓存/速率限制器/审计日志。

变量 描述
MCP_TRANSPORT stdio （默认）或 http
PORT HTTP端口（默认 3000)
ALLOWED_HOSTS / ALLOWED_ORIGINS 逗号分隔的分配列表用于DNS重新绑定保护
ENABLE_DNS_REBINDING_PROTECTION 启用源/主机检查（需要一个分配列表）

多用户（YNAB OAuth）。 配置YNAB OAuth应用程序+ ENCRYPTION_KEY + PUBLIC_URL 并且服务器成为与以下对象联合的OAuth 2.1授权服务器 YNAB：许多用户将自己的YNAB帐户连接到一个实例，每个实例都是隔离的， 在同意的情况下选择只读或读写。看 docs/REMOTE_HOSTING.md 获取完整的部署人员指南 （注册YNAB应用程序、存储、TLS）。

单用户（标头身份验证）。 如果OAuth变量未全部设置，则HTTP模式 通过以下方式获取每个请求的YNAB令牌 X-YNAB-Token 标题（回落到 YNAB_ACCESS_TOKEN 对于一个用户）。 在TLS后面服务。

MCP_TRANSPORT=http PORT=3000 YNAB_ACCESS_TOKEN=… npm start
# connect an MCP client via the mcp-remote shim:
npx mcp-remote http://localhost:3000/mcp --header "X-YNAB-Token: <your-token>"

Claude桌面集成

添加到您的Claude Desktop配置中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

使用npx（推荐）

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["ynab-mcp"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

使用Docker

{
  "mcpServers": {
    "ynab": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "YNAB_ACCESS_TOKEN",
        "ghcr.io/auzroz/ynab-mcp:latest"
      ],
      "env": {
        "YNAB_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

使用本地构建

{
  "mcpServers": {
    "ynab": {
      "command": "node",
      "args": ["/path/to/ynab-mcp/dist/index.js"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

对话示例

连接后，试着问克劳德：

问题 使用的工具
“我现在的净资产是多少？” ynab_net_worth
“这个月我出去吃饭花了多少钱？” ynab_list_category_transactions
“我有什么订阅？” ynab_detect_recurring
“我的预算状况良好吗？” ynab_budget_health
“我在哪里可以削减开支？” ynab_savings_opportunities
“这个月我走上正轨了吗？” ynab_spending_pace
“将本月与上月进行比较” ynab_monthly_comparison

可用工具（共66个）

分析工具（23）

这些工具提供了基于人工智能的财务见解，超越了YNAB的基本功能：

工具 说明
ynab_detect_recurring 查找订阅模式和定期付款
ynab_spending_analysis 按类别分析支出趋势
ynab_budget_health 通过评分和警报评估整体预算健康状况
ynab_savings_opportunities 确定潜在的省钱领域
ynab_budget_vs_actuals 比较预算支出与实际支出
ynab_quick_summary 预算状态概览
ynab_income_expense 收入与支出明细和趋势
ynab_net_worth 计算所有账户的总净值
ynab_goal_progress 通过预测跟踪目标资金进度
ynab_spending_by_payee 按商户/收款人分析支出
ynab_unused_categories 查找非活动或未使用的类别
ynab_monthly_comparison 月度支出比较
ynab_spending_trends 带预测的多月趋势分析
ynab_cash_flow_forecast 基于计划交易的项目未来现金流
ynab_reconciliation_helper 帮助进行账户对账
ynab_budget_suggestions 根据历史记录获取预算建议
ynab_overspending_alerts 快速检查超速类别
ynab_transaction_search 强大的多过滤器交易搜索
ynab_spending_pace 跟踪每日支出率与目标
ynab_category_balances 快速查询类别余额
ynab_credit_card_status 信用卡余额与支付类别
ynab_age_of_money 货币年龄指标及其解释
ynab_preview_scheduled_transaction 预览计划交易的预算影响

核心YNAB API工具（40）

YNAB API端点的覆盖范围：

User Tools (1)
  • ynab_get_user --获取经过身份验证的用户信息
Budget Tools (3)
  • ynab_list_budgets --列出所有可访问的预算
  • ynab_get_budget --获取详细的预算信息
  • ynab_get_budget_settings --获取预算设置（货币格式等）
Account Tools (3)
  • ynab_list_accounts --列出所有有余额的账户
  • ynab_get_account --获取特定帐户详细信息
  • ynab_create_account --创建新帐户 （写入模式）
Category Tools (7)
  • ynab_list_categories --列出所有类别组和类别
  • ynab_get_category --获取类别详细信息
  • ynab_get_month_category --获取特定月份的类别预算
  • ynab_update_category --更新类别预算金额 （写入模式）
  • ynab_create_category --在组中创建新类别 （写入模式）
  • ynab_create_category_group --创建新的类别组 （写入模式）
  • ynab_update_category_group --重命名类别组 （写入模式）
Payee Tools (7)
  • ynab_list_payees --列出所有收款人（商家/供应商）
  • ynab_get_payee --获取具体收款人详细信息
  • ynab_create_payee --创建新收款人 （写入模式）
  • ynab_update_payee --重命名收款人 （写入模式）
  • ynab_list_payee_locations --列出所有收款人位置以进行映射
  • ynab_get_payee_location --获取具体收款人位置
  • ynab_list_payee_locations_by_payee --列出特定收款人的位置
Month Tools (2)
  • ynab_list_months --列出所有预算月份
  • ynab_get_month --获取包含类别的详细月份摘要
Transaction Tools (11)
  • ynab_list_transactions --使用筛选器列出交易记录
  • ynab_get_transaction --获取交易详情
  • ynab_create_transaction --创建新交易 （写入模式）
  • ynab_create_transactions --批量创建交易 （写入模式）
  • ynab_update_transaction --更新交易 （写入模式）
  • ynab_update_transactions --批量更新交易 （写入模式）
  • ynab_delete_transaction --删除交易 （写入模式）
  • ynab_list_account_transactions --列出特定账户的交易记录
  • ynab_list_category_transactions --列出特定类别的交易记录
  • ynab_list_payee_transactions --列出特定收款人的交易记录
  • ynab_import_transactions --触发关联银行的进口 （写入模式）
Scheduled Transaction Tools (5)
  • ynab_list_scheduled_transactions --列出计划/定期交易
  • ynab_get_scheduled_transaction --获取计划交易详细信息
  • ynab_create_scheduled_transaction --创建计划交易 （写入模式）
  • ynab_update_scheduled_transaction --更新计划交易 （写入模式）
  • ynab_delete_scheduled_transaction --删除计划交易 （写入模式）
Money Movement Tools (1)
  • ynab_list_money_movements --列出不同类别之间的资金流动
System Tools (3)
  • ynab_rate_limit_status -检查API费率限制状态
  • ynab_audit_log --查看写入操作审核日志
  • ynab_health_check -测试API连接

可用提示

除了原始工具访问外，服务器还公开了7个MCP提示——指导工作流 基于YNAB自己的预算方法（四条规则、货币时代、， 真实费用），将多个工具整合到一个审查中。任何MCP 客户端支持 prompts 能力可以直接调用它们。

提示 它做什么
ynab-pulse-check 快速日常风格状态检查
ynab-monthly-review 全面的月末预算审查和下个月的建议目标
ynab-assign-money 给每一美元一份工作——分配未分配的资金
ynab-true-expenses 拥抱你的真实支出——计划不定期/年度成本
ynab-overspending-triage 用冲头滚动——发现并解决超支问题
ynab-age-of-money 让你的钱变老——检查现金缓冲和信用卡浮动
ynab-reconcile-cleanup 每周卫生：协调和类别清理

看 docs/REMOTE_HOSTING.md 了解详情。

技能

我们的MCP服务器使Claude可以访问您的YNAB预算。我们的技能教 Claude YNAB自己的最佳实践——有些独立工作，有些更清晰 当连接时。他们一起将原始预算数据转化为实际的教练。

这 skills/ 目录有15个 克劳德代理技能: 7将此MCP服务器的工具编排为指导性审查，8 独立辅导技能（入门、债务偿还、不定期收入、， 无论是否使用此服务器，都可以获得意外之财、应急资金等 有联系的。每 GitHub发布 将它们作为可下载的拉链附加——请参阅 技能/README.md 查看完整列表和安装说明。

发展

# Run with hot reload
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Fix lint issues
npm run lint:fix

# Type check only
npm run typecheck

MCP检验员测试

npx @modelcontextprotocol/inspector node dist/index.js

建筑

src/
├── index.ts              # Entry point (selects stdio or http transport)
├── server.ts             # Per-user server + tool registration
├── http.ts               # Express app for remote (Streamable HTTP) mode
├── crypto.ts             # AES-256-GCM at-rest token encryption
├── config/               # Environment configuration
├── auth/                 # Remote OAuth: MCP AS provider, YNAB client, sessions
├── storage/              # Pluggable storage (memory / sqlite / postgres)
├── services/             # Core services
│   ├── ynab-client.ts    # YNAB API wrapper with rate limiting
│   ├── rate-limiter.ts   # Token bucket rate limiter
│   ├── audit-log.ts      # Per-user write audit log
│   └── cache.ts          # In-memory TTL cache
├── tools/                # MCP tool implementations
│   ├── user/
│   ├── budgets/
│   ├── accounts/
│   ├── categories/
│   ├── payees/
│   ├── months/
│   ├── transactions/
│   ├── scheduled-transactions/
│   └── analytics/
└── utils/                # Helpers (currency, dates, errors)

安全

特性 描述
只读默认值 写入操作已禁用，除非 YNAB_READ_ONLY=false
令牌安全 永远不要承诺你的 YNAB_ACCESS_TOKEN；使用环境变量
输入验证 所有工具参数均已Zod模式验证
速率限制 针对API配额耗尽的内置保护
审计日志 记录所有写入操作以供审查

贡献

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 进行更改
  4. 运行测试和梳理： npm test && npm run lint
  5. 提交您的更改(git commit -m 'Add amazing feature')
  6. 推到分支(git push origin feature/amazing-feature)
  7. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

相关项目

Built with ❤️ for the YNAB community

相关 MCP