monarch-money

Monarch Money MCP 服务

适用于 Monarch Money 的 MCP 服务——一款个人财务应用，可汇总各金融机构的账户、交易、预算和净资产。该服务让 AI 助手能够读写与 Monarch 网页版／移动版应用中相同的数据，且仅限于你自己的账户。

亮点

• 23 个整合工具，分为两个组（readonly、manage），涵盖账户、余额、净资产、现金流、交易、类别、标签、交易规则和预算
• 加密的本地会话，存储于 ~/.monarch-money-mcp/session.enc——服务绝不会通过工具输入接收 Monarch 密码
• 通过环境变量筛选工具组——可将服务设为严格只读模式，也可手动挑选要向 Agent 公开的具体工具
• 自定义的轻量 GraphQL 传输层，目标地址为 api.monarch.com/graphql——不依赖第三方 Monarch 客户端

为什么要自定义 GraphQL 客户端？

本服务中的工具涵盖账户、交易、预算、规则、类别和净资产。我们评估了现有的 TypeScript Monarch 客户端，但没有找到既能覆盖所需功能范围又在积极维护的客户端。与其封装功能不全的第三方客户端并修补其缺陷，本服务不如直接提供一个小型的自研传输层（shared/src/monarch-client/graphql-transport.ts），刻意保持精简：构建请求，通过带类型的异常呈现身份验证／网络错误，并返回带类型的 data 负载。操作以具名 GraphQL 字符串的形式存放在 shared/src/monarch-client/operations.ts 中，便于通过 grep 搜索，也易于扩展。

身份验证

Monarch 的 /auth/login/ 端点会要求从陌生设备首次登录的用户通过电子邮件 OTP 验证码；Monarch 会将验证码发送到你的收件箱。此外，该端点还设有按 IP 限流和 Cloudflare 机器人验证。这意味着在全新安装中，完全无人值守的电子邮件＋密码登录流程无法实现——用户至少要从电子邮件中读取一次验证码。完成这一次配对后，同一安装即可仅凭凭据登录。

因此，建议粘贴会话令牌，而不是通过环境变量传入凭据。服务支持以下四种身份验证方式，优先级依次递减：

1. 环境变量会话令牌（推荐）

将令牌粘贴到启动器的环境变量中一次即可。无需界面、可自主运行，也无需经过 OTP 验证。

MONARCH_SESSION_TOKEN=<your-token>

令牌获取方式：

• 运行一次 npm run login（选项 3），并从 ~/.monarch-money-mcp/session.enc 中复制令牌（解密后）；或
• 打开 Monarch 网页应用的 DevTools → Network → 任意 /graphql 请求 → 复制 Authorization: Token <…> 标头中的值。

令牌会在启动时解析、验证并持久化到磁盘，因此首次运行后便可不再设置环境变量。

2. 通过工具粘贴令牌

如果无法设置环境变量（例如，某个界面不会公开启动器的环境变量），请调用 monarch_login_with_token 工具并将令牌作为输入。服务会先通过 Monarch 的 me 端点验证令牌，再保存令牌。

3. 环境变量电子邮件＋密码（尽力而为）

在环境变量中设置凭据，让服务登录：

MONARCH_EMAIL=<email>
MONARCH_PASSWORD=<password>
MONARCH_TOTP=<code>          # only if your account has 2FA enabled
MONARCH_EMAIL_OTP=<code>     # only on the first launch from a new install

全新安装后首次启动时，Monarch 会向你的电子邮件地址发送 OTP。服务会在标准错误输出中记录明确的操作说明；设置 MONARCH_EMAIL_OTP=<code> 并重启。之后的启动会复用持久化的 device-uuid，跳过 OTP 验证。

4. 交互式 CLI

cd servers/monarch-money/local
npm run login

提示输入电子邮件、密码、可选的 TOTP，以及（如遇到验证挑战）电子邮件 OTP。随后将加密后的令牌写入 ~/.monarch-money-mcp/session.enc。

会话加密

令牌在静态存储时使用 AES-256-GCM 加密。加密密钥通过 scrypt 从口令派生：

• 如果设置了 MONARCH_SESSION_PASSPHRASE，则使用该口令。
• 否则，口令由机器的主机名（os.hostname()）和当前用户（os.userInfo().username）派生——因此默认情况下，加密文件会绑定到特定机器。

这无法防御已经控制你命令行环境的本地攻击者，但可以防止意外泄露到其他主机（例如，文件被放入备份，并在另一台机器上恢复）。

工具组

工具会被标记为一个或多个组。默认情况下会公开所有工具；设置 MONARCH_ENABLED_TOOL_GROUPS（或 MONARCH_ENABLED_TOOLS / MONARCH_DISABLED_TOOLS）可缩小可用范围。

组	包含内容
readonly	仅查询——账户、交易、余额、净资产、类别、预算、规则。
manage	包含 readonly 中的所有内容，另加数据变更操作——创建／更新／删除交易、标签、规则、预算；刷新账户。

筛选优先级：MONARCH_ENABLED_TOOLS（白名单，精确名称）> MONARCH_ENABLED_TOOL_GROUPS（组筛选）> MONARCH_DISABLED_TOOLS（黑名单，精确名称）。

# Strict read-only deployment
MONARCH_ENABLED_TOOL_GROUPS=readonly

# Deny one specific tool
MONARCH_DISABLED_TOOLS=delete_transaction

# Whitelist exactly two tools
MONARCH_ENABLED_TOOLS=get_transactions,get_accounts

工具

身份验证／会话

工具	组	描述
check_authentication	readonly、manage	验证磁盘上的会话是否有效（调用 Monarch 的 me）；如果未通过身份验证，则返回设置说明。
monarch_login_with_token	manage	将预先获取的会话令牌保存到加密的磁盘存储中。

账户

工具	组	描述
get_accounts	readonly、manage	列出所有已连接账户及其余额和元数据。传入 includeHoldings: true 可为每个账户附加投资持仓。
get_account_balance_history	readonly、manage	返回指定账户在日期范围内的每日余额快照。
set_account_balance_history	manage	为手动账户设置记录的每日余额快照——可使用范围模式（开始／结束／余额），或显式的 { date, balance } 列表。通过 Monarch 的余额历史导入器按日期执行插入或更新。
refresh_accounts	manage	触发上游金融机构同步。

净资产

工具	分组	描述
get_net_worth	readonly, manage	净资产视图。view: "history"（默认）返回时间序列；view: "by_type" 返回按账户类型划分的当前明细。

交易（读取）

工具	分组	描述
get_transactions	readonly, manage	通过 view 以五种形式查询交易：list（默认，支持筛选和分页）、summary（汇总总额）、cashflow（收入／支出／储蓄）、by_category（按类别汇总）、recurring（预测发生记录）。
get_transaction_details	readonly, manage	单笔交易的完整详情，包括其拆分项。

交易（写入）

工具	分组	描述
create_transaction	manage	创建手动交易。
update_transaction	manage	更新交易字段。支持以任意组合传入 amount / date / merchantId / categoryId / notes / hideFromReports / reviewed / tagIds。传入 bulkTransactionIds + categoryId，即可在一次调用中批量重新分类多笔交易。
delete_transaction	manage	永久删除交易。
split_transaction	manage	将一笔交易拆分为多个已分类的部分。

分类和标签

工具	分组	描述
get_categories	readonly, manage	列出所有分类。设置 includeGroups: true 可同时返回顶级分类组。
get_tags	readonly, manage	列出所有标签。
create_tag	manage	创建标签。需要提供 name 和十六进制格式的 color（例如 #19d2a5）；order 由服务分配。
delete_tag	manage	按 id 删除标签。返回 { deleted, errors }；删除结果会通过重新读取确认。

交易规则（自动分类）

工具	分组	描述
get_transaction_rules	readonly, manage	列出已配置的自动分类规则，包括每条规则的条件和操作。
create_transaction_rule	manage	根据一个或多个条件（商户 / 金额 / 分类 / 账户）以及一个或多个匹配操作创建规则。
update_transaction_rule	manage	按 id 更新规则。完全替换——重新提供规则的完整条件和操作（每项至少 1 个）；未提供的任何字段都会从规则中清除。
delete_transaction_rule	manage	按 id 永久删除规则。

预算

工具	分组	描述
get_budgets	readonly, manage	列出已配置的预算。
set_budget_amount	manage	设置某个分类的预算金额。

快速入门

安装

npx monarch-money-mcp-server

身份验证

# Clone the repo, cd into this server, then:
cd local
npm run login
# Prompts for email, password, TOTP — writes encrypted token to ~/.monarch-money-mcp/session.enc

Claude Desktop 配置

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "monarch-money": {
      "command": "npx",
      "args": ["-y", "monarch-money-mcp-server"]
    }
  }
}

重启 Claude Desktop 后即可使用。服务会从磁盘读取加密的会话文件——正常使用无需设置环境变量。

环境变量

变量	必需	说明	默认值
MONARCH_SESSION_TOKEN	否	预先获取的会话令牌；启动时解析，并在首次运行时持久化到磁盘。	（无）
MONARCH_EMAIL	否	用于通过环境变量登录的电子邮件地址（与 MONARCH_PASSWORD 配套使用）。	（无）
MONARCH_PASSWORD	否	用于通过环境变量登录的密码。	（无）
MONARCH_TOTP	否	TOTP 代码（仅在启用 2FA 时使用）。	（无）
MONARCH_EMAIL_OTP	否	电子邮件 OTP 代码（仅在全新安装后首次登录时使用）。	（无）
MONARCH_SESSION_PASSPHRASE	否	覆盖用于加密磁盘上会话文件的密码短语。	monarch-mcp:${HOSTNAME}:${USER}
MONARCH_STATE_DIR	否	覆盖 session.enc 所在的目录。	~/.monarch-money-mcp
MONARCH_ENABLED_TOOL_GROUPS	否	以逗号分隔的要公开的组列表（readonly、manage）。默认启用所有组。	（全部）
MONARCH_ENABLED_TOOLS	否	以逗号分隔的工具名称白名单。设置后，优先级高于组和禁用列表。	（无）
MONARCH_DISABLED_TOOLS	否	以逗号分隔的工具名称黑名单。在应用组筛选后移除指定工具。	（无）

安全注意事项

• 不要通过 MCP 工具传递密码。 身份验证通过 CLI 登录脚本或环境变量进行，绝不通过工具输入进行。工具输入可能会出现在对话记录和提示词缓存中；密码不应放在其中。
• 会话文件在静态存储时经过加密，使用 AES-256-GCM。默认密码短语（主机 + 用户）会将文件绑定到写入该文件的机器。
• 工具组筛选是主要的写入保护机制。 对于严格的只读部署，请设置 MONARCH_ENABLED_TOOL_GROUPS=readonly。
• 读取工具不受限制。 解锁会话后，可不受限制地读取账户和交易数据。如果需要对读取操作进行审批，请在一个会通过自身确认流程包装工具调用的客户端后运行服务。

开发

项目结构

monarch-money/
├── local/                   # Stdio entry point
│   └── src/
│       ├── index.ts                       # Production entry
│       └── index.integration-with-mock.ts # Integration test entry
├── shared/                  # Business logic
│   └── src/
│       ├── server.ts        # MCP server factory
│       ├── tools.ts         # Tool registration glue + group filtering
│       ├── tools/           # One file per tool group
│       ├── monarch-client/  # GraphQL transport + session store
│       └── types.ts
├── scripts/
│   └── login.ts             # Email/password/TOTP CLI flow
└── tests/
    ├── functional/          # Unit tests with mocked client
    ├── integration/         # Full MCP protocol with mocked Monarch
    └── e2e/                 # Hits the real Monarch GraphQL API

运行测试

# From this directory:
npm test                  # Functional tests
npm run test:integration  # Integration tests (builds first)
npm run test:e2e          # E2E tests (requires MONARCH_SESSION_TOKEN)

许可证

MIT