ynab-mcp-server

🚀 ynab-mcp-server

ynab-mcp-server 是一个基于 mcp-framework 构建的 Model Context Protocol (MCP) 服务器。它提供了与 YNAB 预算进行交互的工具，YNAB 的具体网址为 https://ynab.com 。

为了让 AI 能够与该工具交互，您需要获取个人访问令牌，可从 YNAB 的此链接获取：https://api.ynab.com/#personal-access-tokens 。在将此 MCP 服务器添加到任何客户端时，您需要提供个人访问令牌作为 YNAB_API_TOKEN。此令牌绝不会直接发送给大语言模型（LLM），它以环境变量的形式私下存储，仅用于调用 YNAB API。

🚀 快速开始

该项目的目的是通过 AI 对话实现与个人 YNAB 预算的交互。以下是主要的工作流程：

第一次设置

• 提示选择您拥有的预算，如果使用其他工具之前未配置，则会自动引导完成。
• 在环境变量中提供 YNAB_API_TOKEN 和 YNAB_BUDGET_ID。

核心功能

• 预算数据导入：从 YNAB 导入预算数据并解析成 MCP 兼容格式。
• 数据查询：支持对预算数据进行复杂查询，例如按类别、时间范围等筛选。
• 操作反馈：根据用户指令提供操作结果的实时反馈。

✨ 主要特性

• 通过 AI 对话便捷地与个人 YNAB 预算进行交互。
• 提供预算数据导入、复杂数据查询以及操作反馈等核心功能。

📦 安装指南

安装步骤

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 启动服务器：

node dist/index.js

💻 使用示例

基础用法

预算数据导入 (ynab.ts)

export async function fetchBudgetData(token: string, budgetId?: string) {
    // 实现从 YNAB 获取预算数据的逻辑
}

数据查询 (query.ts)

export interface QueryOptions {
    category?: string;
    startDate?: string;
    endDate?: string;
}

export async function queryData(options: QueryOptions) {
    // 实现复杂查询逻辑
}

🔧 技术细节

环境配置

需要指定以下环境变量：

• YNAB_API_TOKEN（必需）
• YNAB_BUDGET_ID（可选）

项目结构

核心文件

• index.js：入口文件，负责初始化 MCP 服务器。
• config.js：配置环境变量和默认值。
• tools/：包含实现的具体工具模块。

工具实现

• 预算数据导入 (ynab.ts)：实现从 YNAB 获取预算数据的逻辑。
• 数据查询 (query.ts)：实现对预算数据进行复杂查询的逻辑。

部署与测试

本地开发

1. 修改工具代码。
2. 运行 npm run build 编译。
3. 启动服务器，自动加载更新的工具。

测试

• 确保所有 API 调用成功且返回正确数据。
• 验证查询功能是否按预期工作。

📚 详细文档

学习资源

• MCP 框架 GitHub
• MCP 框架文档