You Need A Budget (ynab) Mcp

YNAB MCP 服务

用于与 You Need A Budget（YNAB）无缝集成的模型上下文协议（MCP）服务。此服务使 AI 助手能够与您的 YNAB 预算交互，提供强大的自动化和分析能力。

快速安装（Claude Desktop）

{
  "mcpServers": {
    "ynab-mcp": {
      "command": "uvx",
      "args": ["ynab-mcp-server"],
      "env": {
        "YNAB_PAT": "your_token_here",
      }
    }
  }
}

可选环境变量：

"env": {
  "YNAB_DEFAULT_BUDGET_ID": "your_budget_id",
  "YNAB_READ_ONLY": "true"
}

功能

• 完整的预算管理

  • 查看和管理多个预算
  • 跟踪账户余额和交易
  • 监控类别支出和目标

• 交易管理

  • 列出和搜索交易
  • 更新交易详情
  • 管理收款方和类别

• 财务分析

  • 获取全面的财务概览
  • 跟踪支出模式
  • 监控预算进度

目录

• 安装
• 平台专属设置
• 配置
• 可用工具
• 使用示例
• 开发
• 贡献
• 许可证

安装与使用

使用 uvx 时无需安装：

# Run directly (recommended)
uvx ynab-mcp-server

# Or with specific version
uvx [email protected]

用于开发：

# Clone and run from source
git clone https://github.com/yourusername/ynab-mcp-server.git
cd ynab-mcp-server
uv run ynab-mcp-server

平台专属设置

Claude Desktop

1. 找到您的配置文件：

   • MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%/Claude/claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 添加 YNAB MCP 服务配置：

{
  "mcpServers": {
    "ynab-mcp": {
      "command": "uvx",
      "args": ["ynab-mcp-server"],
      "env": {
        "YNAB_PAT": "your_token_here"
      }
    }
  }
}

可选环境变量：

env: {
  "YNAB_DEFAULT_BUDGET_ID": "your_budget_id",
  "YNAB_READ_ONLY": "true"
}

Goose

1. 打开 Goose 设置
2. 转到 MCP 服务部分
3. 添加新服务，配置如下：
   • 名称：ynab-mcp
   • 命令：uvx ynab-mcp-server
   • 环境变量：
     • YNAB_PAT：your_token_here

其他平台

对于其他兼容 MCP 的平台，请使用以下参数进行配置：

• 服务名称：ynab-mcp
• 命令：uvx
• 参数：ynab-mcp-server
• 必需的环境变量：YNAB_PAT

配置

您可以使用环境变量配置服务。您可以将这些变量放在项目根目录的 .env 文件中，也可以在 shell 中设置。

变量	必需	描述
YNAB_PAT	是	您的 YNAB Personal Access Token。
YNAB_DEFAULT_BUDGET_ID	否	如果设置，服务将以单预算模式运行，始终使用此预算 ID。list-budgets 工具将被隐藏。
YNAB_READ_ONLY	否	设置为 true 可禁用所有会更改 YNAB 数据的工具。

获取 YNAB Token

1. 获取 YNAB Token

   • 前往 YNAB 开发者设置
   • 创建新的 Personal Access Token
   • 复制 Token 值

2. 设置环境

   在工作目录中创建 .env 文件：

   YNAB_PAT="your_token_here"
   YNAB_DEFAULT_BUDGET_ID="your_budget_id"
   YNAB_READ_ONLY="true"
   

   或直接设置环境变量：

   export YNAB_PAT="your_token_here"
   

可用工具

该服务提供了一套用于与 YNAB 数据交互的工具。说明介绍了每个工具的用途和推荐用法。

工具	说明
manage-financial-overview	获取、更新或刷新高层级财务概览。这是任何分析的最佳起点，可提供账户余额、目标和重要背景说明。
list-accounts	列出指定预算中的所有账户。可用于获取其他工具所需的账户 ID。
get-month-info	获取单个月份的详细预算信息，包括资金使用时间、预算总额、支出总额和可用总额。进行更改前，请调用此工具检查月度预算状态。
list-categories	列出所有类别、类别组及其预算详情。管理预算金额前，请调用此工具，查看可用项目和已分配金额。
list-transactions	列出指定账户或整个月份的交易。使用此工具调查财务概览中发现的支出模式。
list-scheduled-transactions	列出所有即将发生的预定交易。可用于预测即将到来的账单。
manage-budgeted-amount	为某个类别分配预算金额，或在类别之间转移资金。这是分配资金的主要工具。（只读模式下已禁用写入操作）
bulk-manage-transactions	一次创建、更新或删除多笔交易。比逐笔更改更高效。（只读模式下已禁用写入操作）
manage-scheduled-transaction	创建、更新或删除单笔预定（定期）交易。使用此工具管理定期账单或储蓄转账。（只读模式下已禁用写入操作）
list-payees	列出指定预算中的所有收款方。适用于查找收款方 ID，或识别需要合并的混乱收款方数据。
manage-payees	将多个收款方名称合并为一个名称。使用此工具整理收款方数据。（只读模式下已禁用写入操作）
lookup-entity-by-id	根据 ID 查询特定账户、类别或收款方的名称和详情。当你有 ID 但需要完整背景信息时，可使用此工具。
lookup-payee-locations	查询与收款方关联的地理位置。
list-budgets	列出所有可用的 YNAB 预算（单预算模式下不可用）。

开发

本地设置

1. 克隆代码仓库：

   git clone https://github.com/yourusername/ynab-mcp-server.git
   cd ynab-mcp-server
   

2. 安装依赖项：

   uv sync
   

3. 运行服务：

   uv run ynab-mcp-server
   

调试

使用 MCP Inspector 进行调试：

npx @modelcontextprotocol/inspector uvx ynab-mcp-server

本地开发调试：

cd path/to/ynab-mcp-server
npx @modelcontextprotocol/inspector uv run ynab-mcp-server

你也可以通过以下方式查看日志：

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

构建和发布

# Build package
uv build

# Publish to PyPI
uv publish

贡献

欢迎贡献！以下是你可以提供帮助的方式：

1. Fork 代码仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

请确保你的 PR：

• 遵循现有代码风格
• 包含适当的测试
• 根据需要更新文档

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

致谢

• 感谢 YNAB API 提供核心功能
• 感谢 Model Context Protocol 支持 AI 助手集成