关键词

BeancountBQL财务分析账本数据查询

使用说明

项目简介

Beanquery MCP Server 是一个基于 Model Context Protocol (MCP) 的实验性服务器实现，旨在连接大型语言模型 (LLM) 与 Beancount 财务账本。它利用 Beancount Query Language (BQL) 和 beanquery 工具，使得用户可以通过标准化的 MCP 协议，使用 LLM 客户端查询和分析 Beancount 格式的财务数据。

主要功能点

  • 资源访问: 提供对 Beancount 账本数据的资源访问能力，例如获取 BQL 可访问的表列表和账本中的账户列表。
  • 工具执行: 支持执行 BQL 查询工具，允许 LLM 客户端通过 'run_query' 工具，使用 BQL 语句查询账本数据，并以文本表格形式返回结果。
  • 账本配置: 允许通过 'set_ledger_file' 工具动态设置或更改服务器使用的 Beancount 账本文件。
  • 标准化接口: 遵循 MCP 协议，提供与 LLM 客户端进行标准化 JSON-RPC 通信的接口。

安装步骤

  1. 环境准备: 确保已安装 Python 3.10 或更高版本，并推荐使用 'uv' 进行 Python 项目管理。
  2. 安装服务器: 根据仓库 README.md 提供的 "Usage" -> "Running the Server" 部分，可以使用 'mcp install server.py' 命令将服务器安装到支持 MCP 协议的客户端，例如 Claude Desktop。
  3. 安装依赖: 安装 'beancount' 和 'beanquery' 依赖，可以使用如下命令，具体依赖安装方式请参考仓库 README.md： 
    uv run mcp install server.py --with beancount --with beanquery

服务器配置

MCP 客户端需要配置服务器的启动命令和参数才能连接 Beanquery MCP Server。以下是配置信息示例 (JSON 格式)，请在 MCP 客户端中根据实际情况进行配置：

{
  "serverName": "Beanquery MCP Server",
  "command": "mcp",
  "args": [
    "dev",
    "server.py"
  ],
  "transports": {
    "stdio": {}
  },
  "capabilities": [
    "resources",
    "tools",
    "prompts"
  ],
  "configuration": {
    "BEANCOUNT_LEDGER": "/path/to/your/ledger.bean"  // (可选) Beancount 账本文件路径，也可以通过 set_ledger_file 工具动态设置
  }
}

基本使用方法

  1. 启动服务器: 使用 'mcp dev server.py' 命令启动服务器。
  2. 客户端连接: 在支持 MCP 协议的 LLM 客户端 (如 Claude.ai) 中安装并连接到 Beanquery MCP Server。
  3. 资源访问: 在 LLM 客户端中，可以使用以下资源 URI 获取信息：
    • 'beanquery://tables': 获取 BQL 可访问的表列表。
    • 'beanquery://accounts': 获取账本中的账户列表。
  4. 工具调用: 在 LLM 客户端中，可以调用以下工具执行操作：
    • 'set_ledger_file(filename: string)': 设置要使用的 Beancount 账本文件。
    • 'run_query(query: string)': 执行 BQL 查询，并返回文本结果。

例如，在 Claude.ai 中，你可以指示 Claude 使用 'run_query' 工具查询特定账户的余额，或者使用 'get_accounts' 资源获取账户列表用于进一步分析。

隐私警告

请务必注意仓库 README.md 中提到的隐私警告。Beanquery MCP Server 可能会将部分账本数据传输给 LLM 提供商，因此请谨慎处理敏感财务信息，并尽可能使用自托管的 LLM 后端。

信息

分类

商业系统

访问项目