YNAB Integration Server 使用说明

项目简介

YNAB Integration Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为 LLM 应用提供与 YNAB (You Need A Budget) 集成的能力。通过此服务器，LLM 可以安全、便捷地访问您的 YNAB 财务数据，并执行诸如查询账户余额、查看交易记录以及创建新交易等操作。

主要功能点

账户信息访问: 查看 YNAB 中账户的余额和详细信息。
交易记录查询: 获取指定账户的近期交易记录。
创建交易: 在 YNAB 中创建新的交易记录。
资源管理: 通过标准化的 MCP 资源 URL 访问 YNAB 数据。
工具调用: 提供工具接口，允许 LLM 执行特定操作，例如获取账户余额或创建交易。

安装步骤

安装项目: 打开终端，执行以下命令安装 YNAB Integration Server：
```
uv pip install -e .
```
确保您的系统已安装 'uv' 和 'pip'。如果未安装 'uv'，可以先安装 'pip'，然后使用 'pip install uv' 安装 'uv'。

服务器配置

要使 MCP 客户端能够连接到 YNAB Integration Server，您需要提供服务器的启动配置信息。以下是一个 JSON 格式的配置示例，您可以将其添加到 MCP 客户端的服务器配置中。

{
  "serverName": "YNAB Integration Server",
  "command": "mcp-ynab",
  "args": [],
  "description": "YNAB (You Need A Budget) API 集成",
  "capabilities": [
    "resources",
    "tools"
  ]
}

配置参数说明:

'serverName': 服务器的名称，可以自定义，例如 "YNAB Integration Server"。
'command': 启动服务器的命令。安装完成后，可以直接使用 'mcp-ynab' 命令启动服务器。
'args': 启动命令的参数。本例中，服务器默认配置启动，无需额外参数，因此为空数组 '[]'。
'description': 服务器的描述信息，用于在 MCP 客户端中展示。
'capabilities': 声明服务器提供的能力，包括 'resources'（资源访问）和 'tools'（工具调用）。

YNAB API 密钥配置: YNAB Integration Server 需要 YNAB API 密钥才能访问您的 YNAB 数据。您需要从 YNAB Developer Settings 获取 API 密钥，并将其配置到服务器环境中。

有以下几种配置方式：

环境变量: 设置名为 'YNAB_API_KEY' 的环境变量，值为您的 API 密钥。例如，在终端中执行 'export YNAB_API_KEY=your_api_key'。
MCP 密钥管理系统: 如果您的 MCP 客户端支持密钥管理系统，可以将 API 密钥配置在其中。
'.env' 文件: 在项目根目录下创建 '.env' 文件，并添加 'YNAB_API_KEY=your_api_key' 行。

推荐使用环境变量或 MCP 密钥管理系统来配置 API 密钥，以提高安全性。

基本使用方法

启动服务器: 在终端中执行 'mcp-ynab' 命令启动 YNAB Integration Server。
配置 MCP 客户端: 将上面提供的服务器配置 JSON 添加到您的 MCP 客户端中。确保客户端已正确配置并能连接到 MCP 服务器。
使用资源和工具: 在 MCP 客户端中，您可以使用以下资源 URL 访问 YNAB 数据：
- 'ynab://accounts': 列出所有 YNAB 账户。
- 'ynab://transactions/{account_id}': 获取指定账户的近期交易记录，将 '{account_id}' 替换为实际的账户 ID。
您可以使用以下工具执行操作：
- 'create_transaction': 创建新的交易记录。需要提供 'account_id' (账户 ID), 'amount' (金额，美元), 'payee_name' (收款人名称) 等参数。
- 'get_account_balance': 获取指定账户的当前余额。需要提供 'account_id' 参数。
具体的资源和工具使用方法，请参考 MCP 客户端的文档，并在 LLM 应用中根据需要调用相应的资源和工具。

开发模式

如果您需要进行开发和调试，可以使用以下命令启动开发模式：

task dev

此命令将启动带有热重载和浏览器自动打开的开发服务器，方便您进行代码修改和测试。

关键词