actual-budget-mcp 是一个 MCP（Model Context Protocol）服务器，用于将 Actual Budget 个人财务工具连接到 Claude 等 AI 客户端。它让你通过自然语言与预算数据交互，进行查询、分析和管理。
用途
该服务器旨在让用户用日常语言询问财务状况，并获得真实分析结果，而不仅仅是数据查找。它适合希望在不打开 Actual 应用的情况下管理预算、分析支出趋势或执行批量操作的用户。
主要能力
- 真实分析：提供支出预测、分类趋势、预算与实际对比以及月度摘要。
- 可信写入：每次删除操作都会预览将要删除的内容并等待用户确认；设置环境变量 ACTUAL_READ_ONLY=1 可完全隐藏写入工具，实现只读模式。
- 多币种支持：处理拆分和余额对账，而不仅仅是货币符号。
- 同步修复：通过 repair_sync 重建本地同步状态，解决 @actual-app/api 与服务器不同步导致所有工具报错的问题。
- 自然语言查询：支持英语和西班牙语的自然日期表达，如“last month”、“este mes”、“hace 3 meses”、“yesterday”。
- 交易管理：添加支出、转账和编辑，无需打开 Actual 应用。
- 分类、收款人和规则管理：完整的 CRUD 操作。
- 使用名称而非 ID：可以直接说“Cartera”而不是 UUID，若名称有歧义会提供建议。
- 整洁输出：对齐的表格和清晰的摘要，而非原始 JSON。
- 清晰错误信息：明确指出需要修复的内容。
使用方式
该服务器兼容任何支持 MCP 的客户端，包括 Claude Desktop、Claude Code、Cursor、VS Code、Codex 以及指向本地模型（如 Ollama 或 LM Studio）的自定义设置。
安装选项包括：
- Claude Desktop 扩展：下载 actual-budget-mcp.mcpb 文件，在 Claude Desktop 的“设置 > 扩展”中拖入安装。无需配置文件，密码和会话令牌存储在操作系统钥匙串中。此方式不需要安装 Node.js。
- Claude Code：一条命令即可配置。
- Claude Desktop 配置文件：编辑 claude_desktop_config.json。
- Cursor：通过按钮或手动添加 MCP 服务器。
- VS Code (GitHub Copilot)：通过按钮或编辑 settings.json。
- Codex (OpenAI)：一条命令写入 ~/.codex/config.toml。
- Docker：使用镜像，注意容器内 localhost 指向容器本身，需使用 host.docker.internal 访问宿主机，并挂载 /data 卷以缓存预算。
- 从源码安装：适合贡献者。
配置需要 Actual Budget 服务器运行（本地或远程），以及 Node.js 22.14 或更新版本（桌面扩展除外）。需要设置环境变量：ACTUAL_SERVER_URL、ACTUAL_PASSWORD（或 ACTUAL_SESSION_TOKEN 用于 OIDC 服务器）、ACTUAL_BUDGET_ID（实际应填 Sync ID）。
适用场景
- 个人财务管理：查询支出、预算执行情况。
- 财务分析：获取趋势和预测。
- 自动化操作：通过 AI 添加交易、管理分类和规则。
- 本地隐私保护：使用本地模型时，预算数据保留在本地机器。
限制
- 不支持 ChatGPT：因为 ChatGPT 连接器仅接受远程 MCP 服务器（公共 HTTPS 端点），无法指向本地进程。若需使用 OpenAI 模型，可使用 Codex。
- 需要 Actual 服务器：本地预算必须先同步到服务器才能使用。
- 桌面应用内嵌服务器限制：仅监听 127.0.0.1，端口 5007，且仅在应用打开时运行。
- 数据可见性：你使用的 AI 模型（如 Claude）会看到你询问的预算数据，受该提供商条款约束。
- 缓存管理：每个客户端需要独立的 ACTUAL_DATA_DIR，避免两个进程共享同一缓存导致损坏。
- 会话令牌过期：OIDC 服务器的会话令牌会过期，需要重新获取。
数据与隐私
该服务器不收集任何数据，无遥测、分析或使用报告。它仅连接你配置的 Actual 服务器，预算缓存存储在本地数据目录。凭据由 MCP 客户端管理，服务器以环境变量接收，不写入磁盘。无第三方共享。
