Beanquery MCP
About
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.
Details
- Author
- vanto
- GitHub stars
- 49
- Downloads
- 354
- Categories
- Other
Jump to
- 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
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Beanquery MCPCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
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.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"beanquery mcp": {
"beanquery-mcp": {
"command": "uv",
"args": [
"run",
"mcp",
"install",
"server.py",
"-v",
"BEANCOUNT_LEDGER=$(pwd)/sample.bean",
"--with",
"beancount",
"--with",
"beanquery"
]
}
}
}
}McpServers
{
"beanquery-mcp": {
"command": "uv",
"args": [
"run",
"mcp",
"install",
"server.py",
"-v",
"BEANCOUNT_LEDGER=$(pwd)/sample.bean",
"--with",
"beancount",
"--with",
"beanquery"
]
}
}Beanquery MCP
The Beancount MCP Server is an experimental implementation of the Model Context Protocol (MCP) designed to interface with Beancount ledger files. Leveraging the Beancount Query Language (BQL) and the beanquery tool, this server enables seamless querying and analysis of financial data stored in Beancount format. By integrating MCP, the server facilitates standardized communication between AI assistants and Beancount ledgers, enhancing the accessibility and utility of financial data.
Note: This server is experimental and may undergo significant changes. It is recommended to use it in a development environment and provide feedback for further improvements.
A generated sample ledger can be found in sample.bean
Available Resources and Tools
- Tools:
- set_ledger_file: Set the Beancount ledger file to use for queries (if not set via environment variable).
- run_query: Run a BQL query against the loaded Beancount file.
- Resources:
- beanquery://tables: Get a list of tables that BQL can access.
- beanquery://accounts: Get a list of accounts in the loaded Beancount file.
Example using Claude.ai
For a screenshot with expanded MCP interactions, see here.
⚠️ Privacy Warning
This tool interfaces with language model providers (LLMs) via the Model Context Protocol (MCP), and as such may transmit parts of your Beancount ledger—including potentially confidential or private financial information—to third-party services.Please use this tool with caution, especially when:
- Your ledger contains sensitive data (e.g., client names, salary details, health-related expenses).
- You are using a cloud-hosted or non-self-hosted LLM backend.
Recommendations:
- Mask or redact sensitive data in test ledgers.
- Use self-hosted LLMs when possible.
- Review the data being sent via MCP to ensure compliance with your privacy and security requirements.
> [!CAUTION]
> You are responsible for the protection of your financial data. Do not share ledgers you would not be comfortable exposing.
Setup
Prerequisites
- Python 3.10 or later
- uv for managing Python projects (recommended)
Usage
Running the Server
1. Development Mode:
Use the MCP Inspector to test and debug your server:
mcp dev server.py
2. Claude Desktop Integration:
Install the server into Claude Desktop:
mcp install server.py
- Quick Start:
uv run mcp install server.py -v BEANCOUNT_LEDGER=$(pwd)/sample.bean --with beancount --with beanquery
- Custom Name:
uv run mcp install server.py --name "Beanquery MCP Server" --with beancount --with beanquery
- Environment Variables:
uv run mcp install server.py -v BEANCOUNT_LEDGER=/path/to/your/ledger.bean --with beancount --with beanquery
uv run mcp install server.py -f .env --with beancount --with beanquery
Testing
Run the test suite using pytest:
pytest server_test.py
Contributing
1. Fork the repository.
2. Create a feature branch:
git checkout -b feature-name
3. Commit your changes:
git commit -m "Add feature description"
4. Push to your branch:
git push origin feature-name
5. Open a pull request.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
