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:
- Resources:
Example using Claude.ai
screenshot
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
- Development Mode: Use the MCP Inspector to test and debug your server:
- Claude Desktop Integration: Install the server into Claude Desktop:
Testing
Run the test suite using
pytest:Contributing
- Fork the repository.
- Create a feature branch:
- Commit your changes:
- Push to your branch:
- Open a pull request.
License
This project is licensed under the MIT License. See the
LICENSE file for details.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:
- Resources:
Example using Claude.ai
screenshot
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
- Development Mode: Use the MCP Inspector to test and debug your server:
- Claude Desktop Integration: Install the server into Claude Desktop:
Testing
Run the test suite using
pytest:Contributing
- Fork the repository.
- Create a feature branch:
- Commit your changes:
- Push to your branch:
- Open a pull request.
License
This project is licensed under the MIT License. See the
LICENSE file for details.