Beanquery MCP

@vanto

About Beanquery MCP

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.

#personal-finance #mcp #beancount #plaintext-accounting #plaintextaccounting #model-context-protocol #mcp-server

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "beanquery-mcp": {
      "command": "uv",
      "args": [
        "run",
        "mcp",
        "install",
        "server.py",
        "-v",
        "BEANCOUNT_LEDGER=$(pwd)/sample.bean",
        "--with",
        "beancount",
        "--with",
        "beanquery"
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Beanquery MCP?

Beanquery MCP is an experimental Model Context Protocol (MCP) server that interfaces with Beancount ledger files. It uses the Beancount Query Language (BQL) and the beanquery tool to enable querying and analysis of financial data, allowing AI assistants to interact with Beancount ledgers through a standardized protocol.

How to use Beanquery MCP?

Install with Python 3.10+ and uv (recommended). Run in development mode using mcp dev server.py. Install into Claude Desktop with mcp install server.py, optionally setting the BEANCOUNT_LEDGER environment variable. Use the run_query tool to execute BQL queries and the set_ledger_file tool to specify a ledger file. Access resources at beanquery://tables and beanquery://accounts.

Key features of Beanquery MCP?

Run BQL queries against Beancount ledger files
Set ledger file via tool or environment variable
List accessible BQL tables and accounts
Integrates with MCP for AI assistant communication
Works with Claude Desktop after installation

Use cases of Beanquery MCP?

Query financial data from a Beancount ledger using natural language via an AI assistant
Retrieve a list of accounts or tables for analysis
Test and debug Beancount queries interactively with MCP Inspector

FAQ from Beanquery MCP

What are the prerequisites for Beanquery MCP?

Python 3.10 or later and uv (recommended) for managing the project.

How do I set the Beancount ledger file?

Use the set_ledger_file tool or set the BEANCOUNT_LEDGER environment variable when installing.

What tools does Beanquery MCP provide?

It provides run_query to run BQL queries and set_ledger_file to specify the ledger file.

Is Beanquery MCP stable?

No, the server is experimental and may undergo significant changes. Use in a development environment.

Does Beanquery MCP send my financial data to third parties?

Yes, parts of your ledger may be transmitted to LLM providers via MCP. The README includes a privacy warning and recommends caution, especially with sensitive data.

Frequently asked questions

What are the prerequisites for Beanquery MCP?

Python 3.10 or later and uv (recommended) for managing the project.

How do I set the Beancount ledger file?

Use the `set_ledger_file` tool or set the `BEANCOUNT_LEDGER` environment variable when installing.

What tools does Beanquery MCP provide?

It provides `run_query` to run BQL queries and `set_ledger_file` to specify the ledger file.

Is Beanquery MCP stable?

No, the server is experimental and may undergo significant changes. Use in a development environment.

Does Beanquery MCP send my financial data to third parties?

Yes, parts of your ledger may be transmitted to LLM providers via MCP. The README includes a privacy warning and recommends caution, especially with sensitive data.

Comments

Basic information

More Other MCP servers

Production-ready MCP integrations for AI applications

Klavis-AI

Klavis AI: MCP integration platforms that let AI agents use tools reliably at any scale

5.8K

DeepMark

DeepMark helps teachers deliver rapid, consistent marking with meaningful feedback for every student — in a fraction of the time. What once took a week, now takes one free period.