Beanquery

Beancount MCP Server is an experimental implementation that utilizes the Model Context Protocol (MCP) to enable AI assistants to query and analyze Beancount ledger files using Beancount Query Language (BQL) and the beanquery tool.

python

41

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "vanto-beanquery-mcp": {
      "command": "mcp",
      "args": [
        "dev",
        "server.py"
      ],
      "env": {
        "BEANCOUNT_LEDGER": "YOUR_LEDGER_PATH"
      }
    }
  }
}

Beanquery MCP is an experimental server that enables standardized interaction between AI assistants and Beancount ledgers. It uses Beancount’s querying capabilities to explore and analyze financial data stored in Beancount format, making it easier to query data, run analyses, and integrate with AI workflows in a controlled, development-friendly environment.

How to use

You run the Beanquery MCP server locally and connect to it with an MCP client. The server exposes a minimal set of commands you can use to manage the Beancount ledger and run queries. Typical workflows include loading your ledger, querying accounts and tables, and then asking the MCP client to interpret or summarize the results for you.

How to install

Prerequisites you need before installing are Python 3.10 or newer and uv for managing Python projects.

# Install the server in development mode using the MCP tooling
mcp dev server.py

# Install the server for Claude Desktop integration
uv run mcp install server.py
# Quick Start example with a sample ledger
uv run mcp install server.py -v BEANCOUNT_LEDGER=$(pwd)/sample.bean --with beancount --with beanquery

Additional information

The server provides a couple of practical tools and resources you can use during development and testing.

Available tools

set_ledger_file

Set the Beancount ledger file to use for queries. This configures which ledger Beancount will load for subsequent BQL queries.

run_query

Execute a BQL query against the loaded Beancount file to retrieve data such as tables or accounts.