内容
# monarch-mcp
查询和管理 [Monarch Money](https://www.monarch.com/) 个人财务数据的 MCP 服务器。
提供通过本地 SQLite 镜像对交易记录进行只读 SQL 访问、刷新工具以从 Monarch API 同步数据，以及写入工具以更新、分割、标记和规则管理交易记录。适用于 Claude Code、Claude Desktop 和任何 MCP 兼容的客户端。
## 特性
大多数 Monarch Money MCP 服务器都是 **API 直通** —— 每个工具调用都会命中实时 Monarch API 并返回完整响应。该服务器采用根本不同的方法：
- **本地 SQLite 镜像** —— 交易记录同步到本地数据库，因此查询即时且无 API 延迟。其他 Monarch MCP 不具备此功能。
- **任意 SQL** —— 不使用 `get_transactions(start_date, end_date, limit)` 等固定参数工具，而是提供 `query_transactions(sql)`，允许编写任意 SELECT 查询：JOIN、CTE、窗口函数、聚合。AI 编写查询，而非工具设计者。
- **MCP 资源** —— 唯一暴露 schema、accounts、categories 和 tags 作为 MCP 资源的 Monarch MCP。这为 AI 客户端提供了编写良好查询所需的元数据，而无需消耗大量工具调用。
- **高效使用令牌** —— 预计算资源和 SQL 级别过滤意味着只有相关数据才会跨越网络。其他服务器每次调用都会返回完整 API 有效载荷。
- **零原生依赖** —— 使用 Node.js 内置 `node:sqlite`，无需编译扩展。只需 `npm install` 即可。
- **149 个测试** —— 基于 fixture 的测试套件，无需依赖真实财务数据；写入工具针对模拟 API 进行测试。
- **写入工具** —— 直接针对实时 Monarch API 更新、分割和标记交易记录，以及管理自动分类规则。设计用于“扩展/镜像作为只读传感器，代理作为唯一写入者”的架构。
**权衡：** 该服务器专注于交易记录（SQL 分析 + 写入操作）。对于预算、投资或现金流，请将其与 [robcerda/monarch-mcp-server](https://github.com/robcerda/monarch-mcp-server) 等 API 直通 MCP 结合使用。
## 要求
- Node.js >= 22.0.0（使用 `node:sqlite`）
- 具有身份验证令牌的 [Monarch Money](https://www.monarch.com/) 账户
## 快速入门
```bash
# 1. 克隆并安装
git clone https://github.com/sdeiley/monarch_mcp.git
cd monarch_mcp
npm install
# 2. 初始化数据目录
node src/bin/cli.js init
# 3. 设置身份验证令牌
export MONARCH_TOKEN=<您的令牌>
# 4. 获取交易记录
node src/bin/cli.js refresh
# 5. 启动 MCP 服务器
node src/bin/cli.js serve
```
## 获取身份验证令牌
您需要 Monarch Money 身份验证令牌。选项：
1. **环境变量：** `export MONARCH_TOKEN=<令牌>`
2. **令牌文件：** 创建 `~/.monarch-token`，内容为：`{"token": "<令牌>"}`
要获取令牌，请登录 [app.monarch.com](https://app.monarch.com)，打开浏览器开发者工具，并在任何 GraphQL 请求上找到 `Authorization: Token <值>` 头。
## MCP 配置
添加到您的 `.mcp.json`（Claude Code、Dispatch）：
```json
{
"mcpServers": {
"monarch": {
"type": "stdio",
"command": "node",
"args": ["/path/to/monarch_mcp/src/bin/stdio.js"]
}
}
}
```
或如果全局安装：
```json
{
"mcpServers": {
"monarch": {
"type": "stdio",
"command": "npx",
"args": ["monarch-mcp", "serve"]
}
}
}
```
## 资源
服务器暴露 4 个只读资源：
| 资源 | 描述 |
| --- | --- |
| `monarch://schema` | 数据库模式和元数据 |
| `monarch://accounts` | 所有账户及其交易记录数 |
| `monarch://categories` | 所有类别及其分组/类型 |
| `monarch://tags` | 去重、排序的标签列表 |
## 工具
| 工具 | 描述 |
| --- | --- |
| `query_transactions` | 对交易记录表执行只读 SQL（SELECT/WITH） |
| `refresh_transactions` | 从 Monarch API 刷新本地数据库（`recent` = 3 个月，`full` = 全部历史） |
| `update_transaction` | 设置交易记录的类别、商家名称、备注、日期、隐藏报告、需要审查（写入） |
| `split_transaction` | 替换交易记录的分割；金额必须精确合计为父交易记录；空数组清除分割（写入） |
| `create_tag` | 创建新的交易记录标签，返回标签及其 ID（写入） |
| `set_transaction_tags` | 替换交易记录的完整标签集（写入） |
| `list_rules` | 列出所有交易记录规则及其条件/操作（实时 API 读取） |
| `create_rule` | 创建自动分类规则（条件 + 操作）（写入） |
| `update_rule` | 更新现有规则的 ID；支持通过获取-合并-写入进行部分更新（写入） |
| `delete_rule` | 删除规则的 ID（写入） |
| `get_budget` | 指定月份范围的预算：按类别和分组计划/实际/剩余，灵活总额，目标贡献（实时 API 读取） |
| `set_budget_amount` | 设置类别、分组或灵活预算的计划每月预算金额（写入） |
### 写入工具
标记为“(write)”的工具 **修改您的实时 Monarch Money 账户** —— 它们不是沙盒化的，也没有撤销功能。AI 代理在调用任何工具之前应与用户确认。
注意：
- 交易记录写入工具（`update_transaction`、`split_transaction`、`set_transaction_tags`）**自我验证和自我同步**：在修改后，工具重新从实时 API 获取交易记录，验证请求的更改生效，并将实时状态（包括分割子项）更新到本地镜像。结果为 `{ transaction, verification, mirror }` —— 当 `verification.verified` 和 `mirror.synced` 均为真时，无需 `refresh_transactions`；否则，结果带有警告（和不匹配详细信息），并且该交易记录的镜像在运行 `refresh_transactions` 之前过时。不匹配通常意味着 Monarch 规则或并发编辑覆盖了更改。
- 规则写入（`create_rule` / `update_rule` / `delete_rule`，尤其适用于 `applyToExistingTransactions`）可以一次影响多个交易记录，并且在 `refresh_transactions` 之前仍然可以使镜像过时。
- `split_transaction` 在调用 API 之前验证分割金额合计精确为实时父交易记录金额（精确到分）。金额为支出时为负数。
- `set_transaction_tags` 替换完整的标签集；包括要保留的现有标签 ID。
- 规则创建/更新修改不返回规则实体（Monarch API 限制）；使用 `list_rules` 进行确认。
- `update_rule` 真正支持部分更新：Monarch 更新修改静默忽略部分输入（同时报告成功），因此工具获取规则的当前状态，将您的字段合并到它上面，将读取形状转换为写入形状（类别/标签对象 → ID，商家对象 → 名称），并发送完整输入。目标链接、商业实体、通知和需要用户审查的操作不会被轮流，并可能被更新重置。
- `delete_rule` 将 API 错误的缺失视为成功：Monarch 的 `deleted` 响应字段不可靠（即使删除成功也报告 `false`），并且仅作为 `apiDeletedField` 进行调试。
- 预算没有本地镜像表 —— `get_budget` 和 `set_budget_amount` 都与实时 API 进行交互。预算金额使用 **正支出** 约定（计划 `445` = 计划支出 $445），与交易记录金额相反。`set_budget_amount` 通过重新读取月份预算并比较计划金额（结果中的 `verification.verified`）进行自我验证。分组级别的目标需要 `groupLevelBudgetingEnabled`；`flex: true` 需要固定和灵活的预算系统。
### 交易记录表列
`id`、`amount`、`date`、`merchant_name`、`plaid_name`、`category_name`、`category_group`、`category_type`、`account_name`、`notes`、`tags`、`is_split`、`parent_id`、`pending`、`is_recurring`
金额为支出时为负数，为收入时为正数。
### 示例查询
```sql
-- 本月按类别划分的支出
SELECT category_name, COUNT(*) AS n, ROUND(SUM(amount), 2) AS total
FROM transactions
WHERE date >= '2026-03-01' AND category_type = 'expense'
GROUP BY category_name ORDER BY total
-- 未分类交易记录
SELECT date, merchant_name, amount FROM transactions
WHERE category_name = 'Uncategorized' AND date >= '2026-01-01'
-- 按支出最高的商家
SELECT merchant_name, COUNT(*) AS n, ROUND(SUM(amount), 2) AS total
FROM transactions WHERE amount < 0
GROUP BY merchant_name ORDER BY total LIMIT 10
```
## CLI 命令
```bash
monarch-mcp init # 创建 ~/.monarch/ 数据目录
monarch-mcp refresh # 获取最近的交易记录（3 个月）
monarch-mcp refresh --full # 获取所有交易记录历史
monarch-mcp serve # 启动 stdio MCP 服务器
monarch-mcp --help # 显示帮助
```
## 环境变量
| 变量 | 描述 | 默认值 |
| --- | --- | --- |
| `MONARCH_TOKEN` | 身份验证令牌（刷新和所有写入工具所需） | — |
| `MONARCH_DATA_DIR` | 数据目录路径（保存 `monarch.db`） | `~/.monarch` |
## 开发
```bash
npm test # 运行所有测试
node --test test/db.test.js # 运行特定测试文件
```
## 许可证
MIT
