ynab-mcp

🚀 YNAB MCP Server

这是一个用于与“你需要一个预算”（YNAB）无缝集成的模型上下文协议（MCP）服务器。该服务器使AI助手能够与你的YNAB预算进行交互，提供强大的自动化和分析功能。

🚀 快速开始

快速安装（Claude桌面端）

{
  "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时无需安装

# 直接运行（推荐）
uvx ynab-mcp-server

# 或者指定版本运行
uvx ynab-mcp-server@0.1.1

开发环境安装

# 克隆仓库并从源代码运行
git clone https://github.com/yourusername/ynab-mcp-server.git
cd ynab-mcp-server
uv run ynab-mcp-server

🔧 平台特定设置

Claude桌面端

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个人访问令牌。 | | YNAB_DEFAULT_BUDGET_ID | 否 | 如果设置，服务器将以单预算模式运行，始终使用此预算ID。list-budgets工具将被隐藏。 | | YNAB_READ_ONLY | 否 | 设置为true可禁用所有对YNAB数据进行更改的工具。 |

获取你的YNAB令牌

1. 获取YNAB令牌
   • 访问YNAB开发者设置
   • 创建一个新的个人访问令牌
   • 复制令牌值
2. 设置环境变量 创建一个.env文件，内容如下：

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

或者直接在shell中设置环境变量：

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检查器进行调试：

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

构建和发布

# 构建包
uv build

# 发布到PyPI
uv publish

🤝 贡献代码

欢迎贡献代码！你可以按照以下步骤进行：

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

请确保你的拉取请求：

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

📄 许可证

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

🙏 致谢

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