beanquery

Beanquery MCP Server provides a Beancount-focused MCP service that uses Beancount and beanquery to expose financial data and tables via MCP-compatible queries and resources. You can load a Beancount ledger and then run BQL queries against that ledger, discover available tables, and list accounts accessible to BQL. Tools exposed include set_ledger_file for selecting the ledger and run_query to execute BQL queries. This setup enables AI assistants to interact with financial data in a standardized, queryable manner, while also offering a preview of available resources via beanquery://tables and beanquery://accounts.

To use the server, start it with the environment pointing to your ledger or pass it at runtime. Once running, you can interact with the endpoints/tools through your MCP client integration (e.g., Claude Desktop, or an MCP-enabled client). The server is designed for experimentation and development, so expect evolving features and potential changes as feedback is incorporated.

Prerequisites:

• Python 3.10 or later
• uv (recommended) for managing Python projects

1. Install Python dependencies

# If you have a requirements.txt provided by the project
pip install -r requirements.txt

2. Prepare your environment

• Create or choose a Beancount ledger file (e.g., sample.bean).
• Optional: set BEANCOUNT_LEDGER to the ledger file path.

export BEANCOUNT_LEDGER=/path/to/your/ledger.bean

3. Run the MCP server in development mode

uvx run server.py

4. Verify installation

pytest server_test.py

5. Optional Claude Desktop integration (as described in the README)

uv run mcp install server.py -v BEANCOUNT_LEDGER=$(pwd)/sample.bean --with beancount --with beanquery

Tips and considerations:

• The server is marked experimental; use in a development environment and provide feedback.
• If you encounter issues loading the ledger, ensure your Beancount file is valid and accessible at the path specified by BEANCOUNT_LEDGER.
• Be mindful of privacy; sensitive financial data may be transmitted when using MCP with external LLM backends. Mask or redact data in test environments.
• The available tools include set_ledger_file to select the ledger and run_query to execute BQL queries. The resources beanquery://tables and beanquery://accounts expose what’s available for querying.
• Environment variables: BEANCOUNT_LEDGER is the primary one; you can also load configurations from a .env file if supported by your setup.