Actual Budget MCP 服务器

关键词

资源管理实际预算工具执行自然语言接口JSON-RPC

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个功能完备的 MCP 服务器，用于在 AI 助手（如 LibreChat、LobeChat）与 Actual Budget 之间提供标准化的上下文服务。核心能力包括资源管理、工具注册与执行、以及 Prompts 的定义与渲染，所有通过 JSON-RPC 进行通信。

  • 主要功能点

    • MCP 协议核心：实现工具加载、工具调用、并向客户端返回标准化的 JSON-RPC 响应，支持会话管理和能力声明。
    • 资源与工具管理：对 62 种工具进行集中管理，提供分门别类的工具集合，便于 LLM 客户端按需调用。
    • 数据访问与 Actual Budget 连接：通过 Actual Budget API 进行数据读写，提供账户、交易、预算、分类、支付人等操作的工具封装。
    • 认证与安全：支持 Bearer Token 基础认证，以及可选的 OIDC/JWT 验证和按用户的预算 ACL 访问控制。
    • 多传输与扩展性：HTTP(REST JSON-RPC) 作为默认传输，文档内还强调支持 SSE/WebSocket 传输的扩展能力（当前实现核心以 HTTP 为主）。
    • 测试与演练支持：包含单元测试、工具 smoke 测试与 E2E 测试框架，确保工具和协议的正确性与稳定性。

  • 安装步骤

    • 本地开发
      • Node.js 20 及以上环境
      • 安装依赖并构建：npm install，npm run build
      • 启动 HTTP MCP 服务：npm run dev -- --http
    • Docker 部署
      • 使用官方镜像部署，按照文档提供的命令运行容器，暴露端口3600，并配置真实的 Actual Budget 服务地址、口令和同步 ID。
      • 典型运行参数示例（需环境变量覆盖实际环境）：
        • ACTUAL_SERVER_URL、ACTUAL_PASSWORD、ACTUAL_BUDGET_SYNC_ID
        • MCP_SSE_AUTHORIZATION（Bearer 令牌）
        • 如需 HTTPS，请配置 MCP_ENABLE_HTTPS、MCP_HTTPS_CERT、MCP_HTTPS_KEY
    • 高可用部署
      • 也可通过 docker-compose 部署全栈，并使用 production 配置文件实现生产化部署。

  • 服务器配置（供 MCP 客户端参考，不属于前端代码）

    • 以下 JSON 为 MCP 客户端需要的基本启动信息模板（仅示例说明，不是代码片段）
    • JSON 配置示例 { "serverName": "Actual Budget MCP Server", "command": "npm", "args": ["run", "dev", "--http"], "notes": "在本地开发环境下使用上述命令启动 HTTP 传输的 MCP 服务器。生产环境建议使用 Docker 镜像 agigante80/actual-mcp-server，并通过环境变量进行配置。" }

    说明：

    • MCP 客户端需要的其他配置信息（如服务器名称、命令、参数等）以 JSON 形式提供给用户即可，无需在客户端代码中硬编码。实际的启动参数应结合文档中的环境变量要求与部署方式进行配置。
    • 服务器暴露的默认端点为 http://<host>:3600/http，可按需要在容器/服务中修改端口与路径。

  • 基本使用方法

    • 启动后，客户端（如 LibreChat/LobeChat）通过 MCP HTTP 路径与服务器建立会话，执行以下动作：
      • 初始化会话，获取服务能力与工具列表
      • 调用 tools/list 获取可用工具清单
      • 使用 tools/call 按名称与参数调用具体工具，如实际账户、交易、预算等
      • 使用服务器信息工具如 actual_server_info、actual_server_get_version 等进行自检
    • 常见操作的目标是向 LLM 客户端提供可调用的工具集、资源视图与提示模板，用于实现自然语言对 Actual Budget 的操作和查询。

  • 注意事项

    • 生产环境请启用 HTTPS、强认证（OIDC 或强 Bearer）并对暴露接口进行访问控制。
    • 端到端的工具集覆盖广泛，确保实际 Budgets 的服务器地址、同步 ID、以及所需权限在 MCP 服务器端正确配置。
    • 如果使用 Docker，建议使用同一个 Docker 网络（容器互相直连）以降低网络延迟和提高安全性。

服务器信息

访问项目