MoneyBin MCP Server

关键词

本地数据服务DuckDB 后端AI 助手上下文资源与工具管理JSON-RPC 输出

使用说明（Markdown 要点）

  • 项目简介

    • MoneyBin 的 MCP 服务器实现，负责托管和管理资源（Resources）、注册和执行工具（Tools）、定义与渲染提示模板（Prompts），并通过 JSON-RPC 与 LLM 客户端进行通信。服务器端负责会话管理、能力声明与访问控制，支持多种传输协议（如 stdio、SSE、WebSocket/HTTP 模拟模式等），为本地化的 AI 助手提供安全、可扩展的上下文服务框架。
    • 服务器核心通过 FastMCP 框架实现，提供了完整的工具、资源和提示模板的注册、执行与返回结构，并将 DuckDB 作为后端数据源来支撑查询和数据分析。

  • 主要功能点

    • MCP 核心能力
      • 资源端点（Resources）：提供只读数据端点，如 schema/tables、schema/{table}、accounts/summary、transactions/recent、w2/{year} 等，以 JSON 形式输出。
      • 工具端点（Tools）：实现对数据的查询、列出表、查询交易、获取账户余额、获取 W-2 汇总等，可通过 JSON 输出查询结果。
      • 提示模板（Prompts）：提供对话引导模板，如导入数据、分析开支、预算设定、月度回顾、异常检测、税务准备、账户概览等。
    • 数据与权限
      • DuckDB 为只读模式默认，写操作通过专用写工具（write_tools）并经过隐私与权限校验（如写入到 user/raw 模式的表）。
      • 支持对传输与输出进行截断，避免返回超大输出，以及对输出数据进行安全控制。
    • 服务器与客户端交互
      • 使用 JSON-RPC 风格的请求/响应，客户端通过 MCP 接口调用工具、读取资源、获取 Prompts 等。
      • 支持多种传输协议（stdio、SSE、streaming HTTP 等，按实现细节可变），以适配不同客户端的接入方式。
    • 数据源与后端
      • DuckDB 作为核心数据仓库，提供只读查询、以及在需要时的短时写连接来提交变更（例如导入和转换后再回到只读状态）。
      • 与 MoneyBin 的数据任务（提取、加载、dbt 转换等）紧密整合，支持本地化/私有化部署模式。

  • 安装与运行

    • 依赖与环境
      • 需要 Python 3.11+，以及本仓库 README 的本地工具链（如 uv、DuckDB、dbt、Jupyter、Streamlit 等）所需组件。
      • 通过仓库提供的 CLI 命令入口来启动 MCP 服务，例如 moneybin mcp serve。
    • 启动 MCP 服务
      • 直接通过 MoneyBin 的 CLI 启动：moneybin mcp serve
      • 或指定传输方式：moneybin mcp serve --transport sse（示例，支持 stdio、sse、streamable-http 等）
    • 配置与接入
      • MCP 客户端需要的配置信息为 JSON，包含服务器名称、启动命令及参数等信息，以便连接与注册客户端服务。下方给出示例配置要点（非代码块，便于理解）：
        • server: MoneyBin
        • command: uv
        • args: ["run", "--directory", "/path/to/moneybin", "moneybin", "mcp", "serve"]
        • transport: stdio 或 sse（客户端可选不同传输方式）
        • 注：此配置用于 MCP 客户端建立与 MCP 服务端的连接，实际客户端不需要修改服务器端实现细节。

  • 基本使用方法

    • 运行与接入
      • 启动 MCP 服务器后，LLM 客户端通过 JSON-RPC 调用工具、获取资源、获取 Prompts，并读取返回的 JSON 数据。
      • 客户端可以通过配置指定服务器进程的启动方式（如上面的 command/args），以确保与 MCP 服务器建立连接。
    • 常用任务
      • 查询账户、交易、余额等数据时，使用相应的资源与工具接口。
      • 使用 Prompts 指导 AI 的工作流，如导入数据、分析支出、审计订阅、年度回顾等。
    • 安全与权限
      • 只读查询在默认情况下被开启，敏感写操作通过写工具进行，且对目标 schema 做限制，确保数据安全。
      • 支持多会话并发，DuckDB 的只读连接可以并发读取，写操作通过短时连接实现。

  • 你可以期待的结果

    • 稳定地为本地 AI 助手提供金融数据的上下文与分析能力。
    • 将资源、工具、提示模板统一暴露给客户端，以实现标准化的交互模式。

  • 额外说明

    • 该实现包含了完整的 MCP 服务器端代码、资源、工具、提示模板以及对应的测试用例，覆盖从服务器生命周期、数据库连接管理、数据模型、隐私与查询权限、到 CLI 集成等多方面功能。

服务器信息

访问项目