关键词

Beancount账本财务BQL交易

使用说明

项目简介

Beancount MCP Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务器，专为 Beancount 纯文本复式记账系统设计。它允许大型语言模型 (LLM) 客户端通过标准化的 MCP 协议，安全、便捷地访问和操作 Beancount 账本数据，例如查询账户余额、提交新的交易记录等。

主要功能点

  • 账本数据访问 (Resources):
    • 提供Beancount账本中的账户列表和文件列表，方便LLM理解账本结构。
  • 账本查询 (Tools):
    • 支持使用 Beancount Query Language (BQL) 查询账本数据，例如查询特定时间段内的账户余额、交易记录等，并将结果以JSON格式返回。
  • 交易提交 (Tools):
    • 允许LLM提交新的 Beancount 交易记录到账本，实现自动化记账。
  • 实时文件监控:
    • 自动监控 Beancount 账本文件的变化，并在文件更新时自动重新加载，保持数据同步。

安装步骤

  1. 克隆仓库: 
    git clone https://github.com/StdioA/beancount-mcp.git
cd beancount-mcp
  2. 安装依赖: 确保你的Python环境中安装了 'uvicorn' 和 'pip'，然后使用 'pip' 安装项目依赖： 
    pip install .

服务器配置

MCP 客户端需要配置以下信息以连接到 Beancount MCP Server。以下是 JSON 格式的配置信息，可以直接复制到 MCP 客户端的配置文件中。

{
  "server_name": "beancount",
  "command": "uvx",
  "args": [
    "beancount-mcp",  // 运行 beancount-mcp 服务器
    "--transport=sse", // 使用 SSE (Server-Sent Events) 传输协议，也可以选择 stdio
    "<your_ledger.bean>" //  **请替换为你的 Beancount 账本文件路径**
  ]
}

参数说明:

  • 'server_name': 服务器名称，设置为 "beancount"。
  • 'command': 运行服务器的命令，这里使用 'uvx' 启动 'beancount-mcp'。 你需要确保 'uvx' 命令在你的系统路径中可用。 如果你没有安装 'uvx'， 你可以使用 'python -m beancount_mcp.main' 代替 'uvx beancount-mcp'， 并确保 Python 环境配置正确。
  • 'args': 传递给 'beancount-mcp' 命令的参数列表。
    • '"beancount-mcp"': 指定运行 'beancount-mcp' 服务器。
    • '"--transport=sse"': 指定使用 SSE 传输协议。 可以根据客户端和网络环境选择 'sse' 或 'stdio'。
    • '"<your_ledger.bean>"': 请务必替换为你的实际 Beancount 账本文件的路径。 例如 '/path/to/your/ledger.bean'。

注意: MCP 客户端需要能够执行 'uvx beancount-mcp' 命令。 请确保 'uvx' 已安装，或者根据你的环境调整 'command' 和 'args' 配置。

基本使用方法

  1. 启动服务器: 在命令行中，使用 'uvx beancount-mcp <your_ledger.bean>' 命令启动服务器，将 '<your_ledger.bean>' 替换为你的 Beancount 账本文件路径。 例如：

    uvx beancount-mcp my_ledger.bean

    或者，如果选择 'stdio' 传输协议，可以这样启动：

    uvx beancount-mcp --transport=stdio my_ledger.bean

  2. 配置 MCP 客户端: 将上面提供的服务器配置 JSON 添加到你的 MCP 客户端配置中。

  3. 通过 MCP 客户端与服务器交互: 客户端启动后，即可通过 MCP 协议与 Beancount MCP Server 进行通信，调用 'beancount_query' 查询账本数据，调用 'beancount_submit_transaction' 提交交易等。 具体工具和资源的使用方法请参考 MCP 客户端的文档。

常用工具 (Tools):

  • 'beancount_query': 执行 BQL 查询。 例如，查询 "SELECT sum(position) WHERE account ~ 'Expenses' AND date >= 2024-01-01"。
  • 'beancount_accounts': 获取所有账户列表。
  • 'beancount_submit_transaction': 提交 Beancount 交易。 例如，提交一段符合 Beancount 语法的交易字符串。
  • 'beancount_get_transaction': 根据交易 ID 获取交易详情。
  • 'beancount_current_date': 获取当前日期。

常用资源 (Resources):

  • 'beancount://accounts': 获取所有账户列表。
  • 'beancount://files': 获取所有账本文件列表。

请根据你的 MCP 客户端的具体使用方式，参考客户端文档来调用这些工具和资源。

信息

分类

商业系统

访问项目