Beanquery MCP

🚀 Beanquery MCP Server

Beanquery MCP Server is an experimental implementation that aims to interface with the Model Context Protocol (MCP) and interact with Beancount ledger files. By leveraging the Beancount Query Language (BQL) and the beanquery tool, this server enables seamless querying and analysis of financial data stored in Beancount format. Through the integration of MCP, it standardizes communication between AI assistants and Beancount ledger files, enhancing the accessibility and usability of financial data.

🚀 Quick Start

Prerequisites

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

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: Use the -v or --env-file option to specify the path to the environment file, for example:

     uv run mcp install server.py --env-file ./env
     

✨ Features

• Tools:
  • Set Ledger File: Set the Beancount ledger file for querying (if not set via environment variables).
  • Run Query: Execute BQL queries on the loaded Beancount file.
• Resources:
  • beanquery://tables: Get a list of tables accessible via BQL.
  • beanquery://accounts: Get a list of accounts in the loaded Beancount file.

💻 Usage Examples

Using Claude.ai

For detailed screenshots of extended MCP interactions, see here.

📚 Documentation

Available Resources and Tools

• Tools:
  • Set Ledger File: Set the Beancount ledger file for querying (if not set via environment variables).
  • Run Query: Execute BQL queries on the loaded Beancount file.
• Resources:
  • beanquery://tables: Get a list of tables accessible via BQL.
  • beanquery://accounts: Get a list of accounts in the loaded Beancount file.

Contribution Guide

Create a Feature Branch

git checkout -b feature/new-feature-name

Commit Code

git add .
git commit -m "Commit message"
git push origin feature/new-feature-name

Create a Pull Request

1. Navigate to the project's repository page on GitHub.
2. Click the "New Pull Request" button.
3. Select the source branch (e.g., feature/new-feature-name) and the target branch (usually main or develop).
4. Fill in the pull request description and submit.

🔧 Technical Details

Beanquery MCP Server is an experimental implementation that interfaces with the Model Context Protocol (MCP) and interacts with Beancount ledger files. It uses the Beancount Query Language (BQL) and the beanquery tool to query and analyze financial data stored in Beancount format.

📄 License

This project is licensed under the MIT License. For more details, see the LICENSE file.

⚠️ Important Note

This server is in an experimental phase and may undergo significant changes. It is recommended to use it in a development environment and provide feedback for further improvement.

⚠️ Important Note

This tool interfaces with language model providers (LLMs) via the Model Context Protocol (MCP) and may transmit parts of your Beancount ledger file, including potentially confidential or sensitive financial information, to third - party services. Use this tool with caution if your ledger file contains sensitive data or if you are using a cloud - hosted or non - self - hosted LLM backend.

💡 Usage Tip

• Mark or redact sensitive data in test ledger files.
• Use self - hosted LLMs whenever possible.
• Review the data sent via MCP to ensure it meets your privacy and security requirements. You are responsible for protecting your financial data. Do not share ledger files that you would not want to be made public.