Actual Budget MCP Server

Actual Budget MCP 服务

用于将 Actual Budget 与 Claude 及其他大模型助手集成的 MCP 服务。

概览

Actual Budget MCP 服务允许你通过大模型，以自然语言与 Actual Budget 中的个人财务数据交互。它通过模型上下文协议（MCP）提供账户、交易和财务指标。

功能

资源

• 账户列表 - 浏览所有账户及其余额
• 账户详情 - 查看特定账户的详细信息
• 交易记录 - 访问包含完整详情的交易数据

工具

交易与账户管理

• get-transactions - 按账户、日期、金额、类别或收款方检索和筛选交易
• create-transaction - 在账户中创建新交易，可选填写类别、收款方和备注
• update-transaction - 更新现有交易的类别、收款方、备注或金额
• get-accounts - 获取所有账户及其当前余额和 ID 的列表
• balance-history - 查看账户余额随时间的变化

报告与分析

• spending-by-category - 按类型生成支出明细
• monthly-summary - 获取每月收入、支出和储蓄指标
• budget-vs-actual - 按类别比较预算金额与实际支出
• net-worth - 跟踪所有账户中资产、负债和净资产随时间的变化
• category-trends - 查看各类别支出的逐月变化及趋势方向
• spending-by-payee - 按支出金额（或收款金额）对收款方进行排名
• cash-flow - 按月或按周报告收入、支出和净现金流

上述五个工具返回的是 JSON，而非 Markdown，因此金额可供机器读取。每个金额都是以分为单位的整数，每个响应都包含一个 amountsIn 字段，用于说明所采用的符号约定。

自定义报告与仪表板

• get-custom-reports - 获取“报告”部分中保存的所有自定义报告
• create-custom-report - 创建自定义报告并保存
• update-custom-report - 更新已保存自定义报告的字段，其余内容保持不变
• delete-custom-report - 删除自定义报告
• get-dashboards - 获取所有仪表板页面及其布局中的组件
• add-dashboard-widget - 向仪表板页面添加组件
• update-dashboard-widget - 更新组件的配置、位置或大小
• remove-dashboard-widget - 从页面中移除组件
• organize-dashboard - 一次性重新定位和调整多个组件的大小
• create-dashboard-page / rename-dashboard-page / delete-dashboard-page - 管理仪表板页面

类别

• get-grouped-categories - 获取所有类别组及其类别的列表
• create-category - 在类别组中创建新类别
• update-category - 更新现有类别的名称或所属组
• delete-category - 删除类别
• create-category-group - 创建新类别组
• update-category-group - 更新类别组名称
• delete-category-group - 删除类别组

收款方

• get-payees - 获取所有收款方及其详细信息的列表
• create-payee - 创建新收款方
• update-payee - 更新现有收款方的详细信息
• delete-payee - 删除收款方
• merge-payees - 将重复的收款方合并到一个目标收款方中

规则

• get-rules - 获取所有交易规则的列表
• create-rule - 创建包含条件和操作的新交易规则
• update-rule - 更新现有交易规则
• delete-rule - 删除交易规则

提示词

• financial-insights - 根据您的财务数据生成洞察和建议
• budget-review - 分析您的预算执行情况并提出调整建议

安装

前置条件

• Node.js（v16 或更高版本）
• 已安装并配置 Actual Budget
• Claude Desktop 或其他兼容 MCP 的客户端
• Docker Desktop（可选）

远程访问

拉取最新的 Docker 镜像：

docker pull sstefanov/actual-mcp:latest

本地设置

1. 克隆代码仓库：

git clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcp

2. 安装依赖项：

npm install

3. 构建服务：

npm run build

4. 构建本地 Docker 镜像（可选）：

docker build -t <local-image-name> .

5. 配置环境变量（可选）：

# Path to your Actual Budget data directory (default: ~/.actual)
export ACTUAL_DATA_DIR="/path/to/your/actual/data"

# If using a remote Actual server
export ACTUAL_SERVER_URL="https://your-actual-server.com"
export ACTUAL_PASSWORD="your-password"

# Specific budget to use (optional)
export ACTUAL_BUDGET_SYNC_ID="your-budget-id"

# How long downloaded data stays fresh before the server re-syncs, in ms
# (default: 60000). Use 0 to sync before every call, or -1 to never sync.
export ACTUAL_SYNC_TTL_MS="60000"

可选：单独设置加密预算密码

如果您的 Actual 设置要求使用与服务身份验证密码不同的密码来解锁本地／加密预算数据，可以在 ACTUAL_PASSWORD 之外设置 ACTUAL_BUDGET_ENCRYPTION_PASSWORD。

# If server auth and encryption/unlock use different passwords
export ACTUAL_BUDGET_ENCRYPTION_PASSWORD="your-encryption-password"

可选：OpenID 服务（会话令牌身份验证）

如果您的 Actual 服务使用 OpenID 登录（例如 Google），并启用了 ACTUAL_OPENID_ENFORCE=true，密码登录会被禁用，因此无法使用 ACTUAL_PASSWORD。请改为在浏览器中登录 Actual，并传入由此获得的会话令牌。该令牌的优先级高于 ACTUAL_PASSWORD。

export ACTUAL_SERVER_URL="https://your-actual-server.com"
export ACTUAL_SESSION_TOKEN="your-session-token"

要查找令牌，请在浏览器中登录 Actual，打开 DevTools，然后前往 Application → IndexedDB → actual → asyncStorage。user-token 键的值就是您的会话令牌。它是一个 UUID（例如 3f2b8c1e-9a4d-4e7b-8c2a-1d5e6f7a8b9c），而不是很长的 JWT 格式 bearer 令牌。您可以使用 curl -H "X-ACTUAL-TOKEN: <token>" https://your-actual-server.com/account/validate 验证它；该命令应返回 "validated": true。请像对待密码一样保管它：它可以授予对您预算的完全访问权限。令牌的有效期取决于服务的 ACTUAL_TOKEN_EXPIRATION 设置。如果令牌无效或已过期，MCP 服务仍会启动，但工具调用会失败，并显示 Authentication failed: invalid or expired session token，因为服务会在收到第一个请求时连接到 Actual（--test-resources 会立即报告错误）。请重新登录、更换令牌，然后重启 MCP 服务。

连接生命周期

服务在整个运行期间保持一个共享的 Actual 连接，并通过该连接串行处理预算操作。下载的数据超过 ACTUAL_SYNC_TTL_MS 新鲜度窗口后会重新同步。在 stdio 和 HTTP 模式下，SIGINT 和 SIGTERM 都会先等待正在执行的任务完成，再关闭服务。Actual 不再针对每次工具调用分别初始化和关闭。

报告语义

• 余额和余额历史数据均以截至今天为上限；排除日期在未来的交易，当前月份的余额历史记录仅包含部分数据。
• 历史报告仍会纳入已关闭的预算内账户；默认情况下，已关闭的预算外账户仍会被排除。
• 月收入遵循 Actual 的收入组元数据。退款会抵消支出，无活动月份也会计入平均值，未分类的转账对则会跳过。
• 月度摘要中已移除原有的 Investments 类别。

在 Claude Desktop 中使用

要在 Claude Desktop 中使用此服务，请将其添加到 Claude 配置中：

在 MacOS 上：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

在 Windows 上：

code %APPDATA%\Claude\claude_desktop_config.json

将以下内容添加到您的配置中……

a. 使用 Node.js（npx 版本）：

{
  "mcpServers": {
    "actualBudget": {
      "command": "npx",
      "args": ["-y", "actual-mcp", "--enable-write"],
      "env": {
        "ACTUAL_DATA_DIR": "path/to/your/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "http://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

### a. Using Node.js (local only):

```json
{
  "mcpServers": {
    "actualBudget": {
      "command": "node",
      "args": ["/path/to/your/clone/build/index.js", "--enable-write"],
      "env": {
        "ACTUAL_DATA_DIR": "path/to/your/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "http://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

b. 使用 Docker（本地或远程镜像）：

{
  "mcpServers": {
    "actualBudget": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/data:/data",
        "-e",
        "ACTUAL_PASSWORD=your-password",
        "-e",
        "ACTUAL_SERVER_URL=https://your-actual-server.com",
        "-e",
        "ACTUAL_BUDGET_SYNC_ID=your-budget-id",
        "sstefanov/actual-mcp:latest",
        "--enable-write"
      ]
    }
  }
}

保存配置后，重启 Claude Desktop。

💡 如果您使用 ACTUAL_SERVER_URL，则 ACTUAL_DATA_DIR 为可选项。

💡 使用 --enable-write 启用写入工具。

运行 SSE 服务

使用 Docker 通过端口公开服务：

docker run -i --rm \
  -p 3000:3000 \
  -v "/path/to/your/data:/data" \
  -e ACTUAL_PASSWORD="your-password" \
  -e ACTUAL_SERVER_URL="http://your-actual-server.com" \
  -e ACTUAL_BUDGET_SYNC_ID="your-budget-id" \
  -e BEARER_TOKEN="your-bearer-token" \
  sstefanov/actual-mcp:latest \
  --sse --enable-write --enable-bearer

⚠️ 重要：使用 --enable-bearer 时，必须设置 BEARER_TOKEN 环境变量。
🔒 如果要通过公共 URL 公开服务，强烈建议这样做。

示例查询

连接后，你可以向 Claude 提出这样的问题：

• “我当前的账户余额是多少？”
• “显示我上个月按类别划分的支出”
• “我 1 月在杂货上的支出是多少？”
• “过去 3 个月我的储蓄率是多少？”
• “这个月我在哪些类别上超支了？”
• “过去一年我的净资产发生了怎样的变化？”
• “我在哪些收款方身上的支出最多？”
• “我的杂货支出呈上升还是下降趋势？”
• “分析我的预算，并建议可以改进的方面”
• “我有哪些自定义报告？”
• “在我的支出计划仪表板中添加一个净资产小组件”
• “重新排列我的仪表板，让现金流卡片在顶部横跨整行”

使用 Codex CLI

Codex 配置示例：

在 ~/.codex/config.toml 中：

[mcp_servers.actual-budget]
url = "http://localhost:3000"

将 Codex 指向与传递给 npm start -- --sse --port <PORT> 的相同端口。

开发

启用自动重建进行开发：

npm run watch

测试与 Actual 的连接

验证服务能否连接到你的 Actual Budget 数据：

node build/index.js --test-resources

调试

由于 MCP 服务通过 stdio 通信，调试可能颇具挑战。你可以使用 MCP Inspector：

npx @modelcontextprotocol/inspector node build/index.js

端到端验证门槛

端到端测试套件（vitest.e2e.config.ts）会通过 Testcontainers 在 Docker 容器中启动真实的 Actual Budget 服务，初始化一个预算，并通过真实的 MCP 客户端经由 stdio 操作它，以验证账户、交易、类别、收款方、规则和导入的数据确实持久化。需要在本地运行 Docker。

在 CI 中，.github/workflows/pr-validation.yml 中的 e2e-test 任务仅在 release-please PR（分支前缀为 release-please--）或 PR 添加了 run-e2e 标签时运行——默认不会在每个 PR 上运行，因为它需要 Docker，且耗时比标准检查更长。

要在本地运行：

npm run build && npm run test:e2e

必须安装并运行 Docker；测试套件会自动拉取并启动 Actual 服务镜像。

项目结构

• index.ts - 主服务实现
• types.ts - API 响应和参数的类型定义
• prompts.ts - 用于与大模型交互的提示词模板
• utils.ts - 用于日期格式化等的辅助函数

注册表与发现

actual-mcp 已发布到官方 MCP 注册表， 名称为 io.github.s-stefanov/actual-mcp。注册表元数据位于 server.json，并会在每次发布时自动发布 （参见 .github/workflows/release-please.yml）。

它在 npm 包中提供两种传输方式——stdio（默认）和 streamable-http（通过 --sse 标志启用）。（此外也会发布 Docker 镜像， 但它目前尚未列为注册表包。）

发布后的目录列表记录在 docs/mcp-registry-checklist.md 中。

许可证

MIT

贡献

欢迎贡献！欢迎随时提交 Pull Request。