BQL Data Accessor (MCP Service)

This implementation of the Model Context Protocol (MCP) server is purpose-built to interact with data managed within Beancount ledger files. It capitalizes on the robust Beancount Query Language (BQL) capabilities, powered internally by the beanquery engine, to enable sophisticated querying and comprehensive analysis of financial entries. By integrating this service via MCP, it standardizes the secure exchange of information requests between AI systems and the ledger, thereby elevating the utility and ease of access for personal financial intelligence.

Note: This server component is currently in an experimental phase and is subject to potential modifications. We encourage early adopters to deploy it in controlled settings and contribute feedback for refinement.

A sample Beancount file for demonstration is provided here: sample.bean

Operational Resources and Functions

Functions (Tools):
set_ledger_file: Designate the path to the Beancount file to be queried (overridable via environment configuration).
run_query: Execute a specified BQL statement against the currently loaded ledger data.
Data Endpoints (Resources):
beanquery://tables: Retrieves a catalog of accessible data structures available to BQL queries.
beanquery://accounts: Fetches the definitive list of all defined ledger accounts.

Demonstration with Claude.ai

For a visual example showing the interaction flow within the MCP framework, refer to here.

🛑 Crucial Data Privacy Advisory

This tool communicates with Language Model Providers (LLMs) using the MCP specification. Consequently, portions of your Beancount ledger—which may include highly sensitive or private financial figures—could be transmitted to external, third-party processing services.

Exercise prudence when utilizing this feature, particularly under these conditions:

Your ledger data encompasses personally identifiable or financially sensitive details (e.g., compensation, investments, proprietary business figures).
The backend LLM infrastructure utilized is cloud-based or not managed internally.

Recommendations for mitigation:

Always sanitize or mask sensitive entries in any ledger used for testing or non-private operations.
Prioritize the deployment of self-hosted or locally-run LLMs for enhanced data control.
Regularly audit the data payload transmitted via MCP to guarantee adherence to all established privacy and security mandates.

[!CAUTION] The onus of safeguarding your proprietary financial information rests entirely with you. Exercise restraint in sharing ledger contents you would deem inappropriate for public disclosure.

Installation Guide

Prerequisites

A functioning installation of Python, version 3.10 or newer.
Installation of uv (recommended dependency manager for Python projects).

Deploying the Server

Debugging/Inspection Mode: To test and monitor server interactions interactively: bash mcp dev server.py
Integration with Claude Desktop: To incorporate the server directly into the Claude Desktop environment: bash mcp install server.py
Rapid Initialization: bash uv run mcp install server.py -v BEANCOUNT_LEDGER=$(pwd)/sample.bean --with beancount --with beanquery
Custom Naming Convention: bash uv run mcp install server.py --name "BQL Financial Interface" --with beancount --with beanquery
Configuration via Environment Variables: bash uv run mcp install server.py -v BEANCOUNT_LEDGER=/secure/path/to/master.bean --with beancount --with beanquery uv run mcp install server.py -f .env --with beancount --with beanquery

Verification

Execute the automated testing suite using the standard Python testing harness:

pytest server_test.py

Contribution Guidelines

Fork the main repository.
Establish a dedicated feature branch for your work: bash git checkout -b enhancement-branch-name
Commit your modifications with a descriptive message: bash git commit -m "Implement feature X improvement"
Push your new branch to the remote repository: bash git push origin enhancement-branch-name
Submit a Pull Request for review.