AI导哈

预算数据查询服务器

YNAB MCP Server是一个只读的预算数据查询服务器，提供预算、账户、交易和类别的查询功能，以及支出分析工具。

  • by arunselvarajdb
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 arunselvarajdb/ynab-mcp-server

使用说明

YNAB MCP服务器

用于与YNAB（您需要预算）预算交互的只读模型上下文协议（MCP）服务器。此服务器提供用于查询预算、账户、交易、类别和生成支出见解的工具和资源。

特性

核心功能

  • 只读访问：安全、无损地访问您的YNAB数据
  • 综合工具：获取预算、账户、交易、类别和收款人
  • 开支分析：用洞察力和统计数据分析支出模式
  • MCP资源：格式化的预算摘要、账户余额和类别支出
  • 安全：通过环境变量、输入验证和错误处理的API令牌
  • 测试良好：全面的单元测试，代码覆盖率>60%

开发工具

  • 任务运行器：与Taskfile.yml的统一命令界面
  • 预提交钩子：每次提交时自动进行代码质量检查
  • 安全扫描：使用Bandit进行代码分析，使用pip审计进行依赖性审计
  • 类型安全：使用MyPy进行完整类型检查
  • 代码质量：使用Ruff进行装订和格式化
  • 秘密侦查：防止意外提交凭据

先决条件

  • Python 3.11或更高版本
  • 紫外线 包管理器
  • YNAB个人访问令牌

快速开始

1.安装任务运行器（可选但推荐）

# macOS
brew install go-task

# Or visit: https://taskfile.dev/installation/

2.完成设置

使用任务（推荐）：

task setup

或手动：

# Install dependencies
uv sync --all-extras

# Copy environment file
cp .env.example .env

# Install pre-commit hooks
uv run pre-commit install

3.配置环境变量

编辑 .env 并添加您的YNAB个人访问令牌：

# Required: Your YNAB Personal Access Token
YNAB_API_TOKEN=your_token_here

# Optional: Default budget ID
DEFAULT_BUDGET_ID=

# Optional: Log level
LOG_LEVEL=INFO

4.获取您的YNAB API代币

  1. 登录您的YNAB帐户
  2. 首选 账户设置 → 开发人员设置
  3. 点击 新令牌 在“个人访问令牌”下
  4. 输入密码以生成令牌
  5. 将令牌复制到您的 .env 文件

安全警告：永远不要承诺你的 .env 文件或共享您的API令牌！

用法

MCP检验员测试

使用MCP检查器交互式测试服务器：

使用任务：

task run:inspect

或者直接：

./inspect-server.sh
# or
npx @modelcontextprotocol/inspector uv run ynab-mcp-server

备注MCP Inspector是一个Node.js工具，因此您需要安装Node.js和npm/npx。

检查员提供：

  • 带参数输入的交互式工具测试
  • 实时响应查看
  • 资源浏览
  • 请求/响应日志记录

可用任务命令

跑 task --list 查看所有可用命令，包括：

设置和安装：

  • task setup -完成项目设置（安装deps、创建.env、安装钩子）
  • task install -安装所有依赖项，包括开发工具
  • task setup:hooks -安装预提交挂钩

代码质量：

  • task check -运行所有质量检查（格式、皮棉、安全性、类型检查、测试）
  • task fmt -带褶皱的格式代码
  • task lint -带褶边的棉绒代码
  • task typecheck -使用mypy进行类型检查

安全：

  • task security -运行所有安全扫描
  • task security:bandit -Python代码安全漏洞
  • task security:deps -依赖漏洞扫描

测试：

  • task test -运行覆盖率测试
  • task test:verbose -运行具有详细输出的测试
  • task test:coverage -生成HTML覆盖率报告

正在运行：

  • task run -在stdio模式下运行服务器
  • task run:http -以HTTP模式运行服务器
  • task run:http:debug -运行调试日志
  • task run:inspect -运行MCP检查器

预承诺：

  • task pre-commit -手动运行所有预提交挂钩
  • task pre-commit:update -将挂钩更新到最新版本

运行MCP服务器

服务器支持两种传输模式：

1.stdio模式（默认）

适用于Claude Desktop或检查器等MCP客户端：

使用任务：

task run

或者直接：

uv run ynab-mcp-server
# or
python -m ynab_mcp_server

2.HTTP/SSE模式

对于基于HTTP的服务器发送事件访问：

使用任务：

task run:http        # Run on port 8000
task run:http:debug  # Run with debug logging

或者直接：

./run-http-server.sh
# or
uv run ynab-mcp-server --transport sse --port 8000

HTTP服务器将在 http://localhost:8000 （或您选择的端口）。

命令行选项：

  • --transport {stdio|sse} -选择传输类型（默认：stdio）
  • --port PORT -HTTP服务器端口（默认值：8000，仅适用于SSE）
  • --host HOST -HTTP服务器主机（默认：localhost，仅适用于SSE）

可用工具

MCP服务器提供以下工具：

get_budgets()

获取已验证用户的所有预算列表。

{
  "budgets": [
    {
      "id": "budget-123",
      "name": "My Budget",
      "currency_format": {
        "iso_code": "USD",
        "currency_symbol": "$"
      }
    }
  ]
}

get_accounts(budget_id: str)

获取特定预算的所有账户。

{
  "budget_id": "budget-123",
  "accounts": [
    {
      "id": "account-1",
      "name": "Checking Account",
      "type": "checking",
      "balance": 1500.00,
      "cleared_balance": 1400.00
    }
  ]
}

get_transactions(budget_id: str, since_date?: str, transaction_type?: str, account_id?: str)

使用可选筛选器获取交易。

参数：

  • budget_id （必填）：预算UUID
  • since_date （可选）：从中检索交易的ISO日期（YYYY-MM-DD）
  • transaction_type （可选）：按类型筛选-“未分类”或“未批准”
  • account_id （可选）：按特定帐户UUID筛选

示例：

# Get all transactions
get_transactions("budget-123")

# Get transactions since specific date
get_transactions("budget-123", since_date="2025-01-01")

# Get unapproved transactions
get_transactions("budget-123", transaction_type="unapproved")

# Get transactions for specific account
get_transactions("budget-123", account_id="account-456")

get_categories(budget_id: str)

按类别组组织所有类别。

{
  "budget_id": "budget-123",
  "category_groups": [
    {
      "id": "group-1",
      "name": "Monthly Bills",
      "categories": [
        {
          "id": "cat-1",
          "name": "Rent",
          "budgeted": 1000.00,
          "activity": -1000.00,
          "balance": 0.00
        }
      ]
    }
  ]
}

get_payees(budget_id: str)

获得所有收款人的预算。

analyze_spending(budget_id: str, category_id?: str, since_date?: str, account_id?: str)

用洞察力和统计数据分析支出模式。

参数：

  • budget_id （必填）：预算UUID
  • category_id （可选）：筛选到特定类别
  • since_date （可选）：分析开始日期（默认为30天前）
  • account_id （可选）：筛选到特定帐户

退货：

{
  "summary": {
    "total_spent": 750.50,
    "transaction_count": 15,
    "average_transaction": 50.03,
    "daily_average": 25.02
  },
  "top_payees": [
    {"payee": "Whole Foods", "amount": 200.00},
    {"payee": "Shell", "amount": 150.00}
  ]
}

可用资源

MCP资源提供格式化的只读数据：

ynab://budgets/{budget_id}/summary

包括账户和类别的全面预算摘要。

ynab://budgets/{budget_id}/accounts

已格式化的账户余额。

ynab://budgets/{budget_id}/categories

类别支出概述和使用百分比。

发展

开发工作流程

使用任务（推荐）：

# Run all quality checks (format, lint, security, typecheck, test)
task check

# Run specific checks
task fmt           # Format code
task lint          # Lint code
task security      # Run security scans
task typecheck     # Type check with mypy
task test          # Run tests with coverage

# Run pre-commit hooks manually
task pre-commit

# See all available tasks
task --list

或者直接使用紫外线：

# Run tests
uv run pytest
uv run pytest --cov              # With coverage
uv run pytest tests/test_tools.py  # Specific file

# Code quality
uv run ruff format src/
uv run ruff check src/
uv run mypy src/

# Security
uv run bandit -r src/ -ll
uv run pip-audit

预提交钩子

每次提交时，预提交钩子都会自动运行：

  • 拉夫 -格式和lint代码
  • 匪徒 -安全检查
  • MyPy 的 -类型检查
  • 检测秘密 -秘密侦查
  • 文件质量检查（尾随空格、YAML语法等）

要手动运行，请执行以下操作：

task pre-commit
# or
uv run pre-commit run --all-files

项目结构

ynab-mcp-server/
   src/
      ynab_mcp_server/
          __init__.py          # Package initialization
          __main__.py          # Entry point
          config.py            # Configuration management
          ynab_client.py       # YNAB API wrapper
          server.py            # MCP server with tools & resources
   tests/
      conftest.py              # Pytest fixtures
      test_tools.py            # Tool tests
      test_resources.py        # Resource tests
   .env.example                 # Example environment variables
   .gitignore                   # Git ignore rules
   pyproject.toml               # Project configuration
   README.md                    # This file

安全最佳实践

API代币安全

  1. 从不硬编码令牌 -始终使用环境变量
  2. 使用 .env 文件 地方发展（已在 .gitignore)
  3. 定期旋转令牌 -建议每60-90天
  4. 监控令牌使用情况 -检查YNAB开发人员设置是否有异常活动
  5. 使用单独的令牌 -用于开发/生产的不同代币

配置验证

服务器在启动时验证配置：

  • 检查是否需要 YNAB_API_TOKEN
  • 拒绝占位符值，如“your_token_here”
  • 验证日志级别是否为有效选项
  • 故障迅速，错误信息清晰

错误处理

  • API令牌从不在错误消息中公开
  • 记录身份验证错误，但不记录令牌详细信息
  • 向用户返回通用错误，详细的调试日志
  • 所有API调用都包装在try-chatch块中

输入验证

  • 验证预算ID、帐户ID和日期
  • Pydantic模型确保类型安全
  • SQL注入不适用（使用YNAB REST API）
  • XSS不适用（无web界面）

API费率限制

YNAB API有费率限制：

  • 每小时200个请求 每个访问令牌
  • 费率限制每小时重置一次
  • 服务器优雅地处理429个响应
  • 考虑将缓存用于生产环境

故障排除

“动态API令牌无效”错误

  • 检查您的令牌 .env 与YNAB开发人员设置中的设置匹配
  • 确保令牌未被撤销
  • 尝试生成新令牌

“未找到预算”错误

  • 验证budget_id是否正确（从以下位置获取 get_budgets() 工具）
  • 确保您的代币可以访问预算
  • 检查预算是否已删除

测试失败

# Reinstall dependencies
uv sync --all-extras

# Clear pytest cache
rm -rf .pytest_cache

# Run with verbose output
uv run pytest -vvs

导入错误

# Reinstall in editable mode
uv pip install -e .

贡献

这是一个个人项目，但欢迎提出建议和反馈！

开发工作流程

  1. 设置: task setup -安装依赖项和预提交挂钩
  2. 开发：进行更改
  3. 质量检查: task check -执行所有质量检查
  4. 测试：确保所有测试通过
  5. 提交：预提交钩子将自动运行
  6. 更新文档：更新README以获取新功能

提交前

# Run all quality checks
task check

# This runs:
# - Code formatting (ruff format)
# - Linting (ruff check)
# - Security scans (bandit, pip-audit)
# - Type checking (mypy)
# - Tests with coverage (pytest)

预提交钩子将在提交时自动执行这些检查。

安全

有关安全问题和漏洞报告，请参阅我们的 安全策略.

快速安全检查表：

  • ✅ 保留YNAB API令牌 .env （从不承诺）
  • ✅ 跑 task security 扫描漏洞
  • ✅ 定期更新依赖关系 uv sync --upgrade
  • ✅ 检查预提交挂钩是否正常工作： task pre-commit

私下向以下人员报告安全漏洞：mit.arun07@gmail.com

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

资源

更新日志

v0.1.0（2025-11-22）

  • 初始版本
  • 预算、账户、交易、类别和收款人的只读工具
  • 与顶级收款人和统计数据进行支出分析
  • 用于格式化预算数据的MCP资源
  • 全面的测试覆盖率
  • 安全最佳实践实施

相关 MCP