Beanquery MCP Server

Overview

Beanquery MCP is an experimental Model Context Protocol server that bridges AI assistants with Beancount ledger files. By exposing Beancount’s native query language (BQL) through MCP, the server lets developers and financial analysts retrieve, filter, and aggregate ledger data directly from conversational agents such as Claude. This eliminates the need for custom parsers or manual SQL conversions, allowing natural language queries to be translated into precise BQL statements behind the scenes.

The server provides a minimal yet powerful set of tools and resources. With developers can point the server at any Beancount file, while executes arbitrary BQL against that ledger. Resources like and expose the underlying schema, enabling agents to introspect available data before crafting queries. These capabilities make it trivial for an AI assistant to answer questions such as “What were my total expenses in Q3 2024?” or “Show me the balance of all equity accounts.”

Key features include:

• Standardized MCP integration: Works with any LLM that supports the protocol, ensuring consistent communication patterns.
• Live ledger querying: Changes to the underlying Beancount file are immediately reflected in query results, ideal for dynamic budgeting or audit scenarios.
• Security awareness: The documentation explicitly warns about potential data exposure, encouraging developers to mask sensitive fields or run the server locally with self‑hosted LLMs.

Typical use cases span personal finance management, small‑business bookkeeping, and compliance reporting. For example, a freelancer could ask their AI assistant to “Show me my tax‑deductible expenses for the last year,” and receive a BQL result without ever opening a spreadsheet. In an enterprise setting, the server could feed real‑time financial dashboards or trigger automated alerts when account balances breach thresholds.

Integrating Beanquery MCP into an AI workflow is straightforward: once the server is running, any MCP‑capable client can call with a natural language prompt. The server translates the prompt into BQL, executes it against the chosen ledger, and returns structured data. This tight coupling between conversational agents and financial data unlocks powerful automation—automated month‑end reconciliations, instant variance analyses, or even AI‑driven investment advice—all while keeping the data in its native Beancount format.