内容
# YNAB MCP 服务器
与您的财务进行对话。
## 这是什么？
[YNAB（你需要一个预算）](https://ynab.com)是一款流行的预算应用程序，帮助您控制您的资金。该MCP服务器将AI助手连接到您的YNAB数据，使您能够以对话方式访问：
- 您的预算和账户
- 交易历史和模式
- 类别余额和支出洞察
- 预定和重复交易
- 创建和管理交易
- 更新类别预算
- 创建账户
## 安装
### 通过 npx（推荐）
无需安装。配置您的Claude客户端以直接使用npx（参见下文）。
### 通过 npm（全局）
```bash
npm install -g ynab-mcp-server
```
### 从源代码
```bash
git clone https://github.com/jeangnc/ynab-mcp-server.git
cd ynab-mcp-server
make install
make build
```
## 配置
首先，在您的shell配置文件（`~/.zshrc`或`~/.bashrc`）中设置您的YNAB API令牌：
```bash
export YNAB_API_TOKEN="您的令牌"
```
### Claude 代码
```bash
claude mcp add ynab --scope user --env YNAB_API_TOKEN='${YNAB_API_TOKEN}' -- npx -y ynab-mcp-server
```
### Claude 桌面
添加到 `~/.config/claude/claude_desktop_config.json`（Linux）或 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
```json
{
"mcpServers": {
"ynab": {
"command": "npx",
"args": ["-y", "ynab-mcp-server"],
"env": {
"YNAB_API_TOKEN": "${YNAB_API_TOKEN}"
}
}
}
}
```
### 手动使用
```bash
YNAB_API_TOKEN=$YNAB_API_TOKEN npx ynab-mcp-server
```
## 可用工具
### 读取工具
| 工具 | 描述 |
|------|-------------|
| `list_budgets` | 获取认证用户的所有预算。返回预算名称、ID和最后修改日期。 |
| `get_budget` | 获取特定预算的详细信息，包括账户、类别和设置。 |
| `list_accounts` | 获取预算的所有账户。返回账户名称、类型、余额和状态。 |
| `get_account` | 获取特定账户的详细信息。 |
| `list_categories` | 获取预算的所有类别，按类别组分组。包括预算金额和活动。 |
| `get_category` | 获取特定类别的详细信息，包括当前月份数据。 |
| `list_transactions` | 获取预算的交易。支持按日期、类型、类别、收款人和账户过滤。 |
| `get_transaction` | 获取特定交易的详细信息。 |
| `list_payees` | 获取预算的所有收款人。 |
| `list_scheduled_transactions` | 获取预算的所有预定/重复交易。 |
| `list_months` | 获取预算的所有月份。返回月份摘要，包括收入、预算和活动总额。 |
| `get_month` | 获取特定月份的预算详细信息，包括所有类别余额。 |
### 写入工具
| 工具 | 描述 |
|------|-------------|
| `create_transaction` | 创建新的交易。金额应为负数（支出）或正数（收入）。 |
| `update_transaction` | 更新现有交易。仅提供要更改的字段。 |
| `delete_transaction` | 删除现有交易。 |
| `update_category_budget` | 更新特定月份类别的预算金额。 |
| `create_account` | 在预算中创建新账户。 |
| `get_scheduled_transaction` | 获取特定预定交易的详细信息。 |
| `create_scheduled_transaction` | 创建新的预定/重复交易。日期必须在未来（最多5年）。 |
| `update_scheduled_transaction` | 更新现有预定交易。仅提供要更改的字段。 |
| `delete_scheduled_transaction` | 删除现有预定交易。 |
| `update_payee` | 更新收款人姓名。名称必须为500个字符以内。 |
### 历史工具
| 工具 | 描述 |
|------|-------------|
| `list_history` | 列出最近的写入操作及其ID以便撤销。操作按时间倒序列出（最新的操作在前）。 |
| `get_history_entry` | 获取特定历史记录条目的详细信息，包括前后状态。 |
| `undo_operation` | 通过历史记录ID撤销以前的写入操作。 |
## 历史记录和撤销
服务器跟踪所有写入操作（交易、预定交易、类别预算、收款人和账户），并允许您撤销它们。
### 工作原理
- 所有写入操作自动记录到 `~/.ynab-mcp-history.json`
- 历史记录在服务器重启后仍然存在
- 最多保留100个操作（最旧的操作自动删除）
- 使用 `list_history` 查看最近的操作及其ID
- 使用 `undo_operation` 和条目ID撤销更改
### 支持的撤销操作
| 操作 | 撤销操作 |
|-----------|-------------|
| 创建交易 | 删除创建的交易 |
| 更新交易 | 恢复到以前的状态 |
| 删除交易 | 重新创建交易（新的ID） |
| 创建预定交易 | 删除创建的预定交易 |
| 更新预定交易 | 恢复到以前的状态 |
| 删除预定交易 | 重新创建预定交易（新的ID） |
| 更新类别预算 | 恢复以前的预算金额 |
| 更新收款人 | 恢复以前的名称 |
| 创建账户 | **无法撤销**（YNAB API限制） |
### 限制
- **账户创建无法撤销**：YNAB API不支持删除账户
- **重新创建的交易具有新的ID**：当撤销删除时，交易会重新创建并具有新的ID
- **外部更改**：如果数据在MCP服务器外部被修改，撤销可能会失败或产生意外的结果
- **旧的历史记录条目**：非常旧的条目可能引用不再存在的实体
## Makefile 命令
```
make install # 安装依赖项
make build # 编译TypeScript
make run # 运行编译后的服务器
make dev # 直接运行TypeScript
make clean # 删除构建产物
```
