Beancount Query
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.
What is Beancount Query?
Beancount Query is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to 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...
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.
This server falls under the Finance & Fintech category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Beancount MCP Server is an experimental implementation that
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx beanquery-mcp-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Beancount Query
Beanquery MCP Server connects AI assistants to your Beancount plaintext accounting ledger, enabling natural-language queries over your personal or business financial data using Beancount Query Language (BQL). It exposes two tools — one to run arbitrary BQL queries and one to set the active ledger file — along with resources for listing tables and accounts. This makes it easy to ask questions like 'show me all expenses in Q1' or 'what is my net worth' directly from an AI chat interface without leaving your terminal.
Prerequisites
- Python 3.10+ with uv package manager installed
- Beancount installed (pip install beancount) and a .bean ledger file on disk
- beanquery tool installed (pip install beanquery)
- An MCP client such as Claude Desktop
- The BEANCOUNT_LEDGER environment variable set to the absolute path of your ledger file
Install uv and clone the repository
The server is run directly from source using uv. Clone the repository and enter the directory.
git clone https://github.com/vanto/beanquery-mcp.git
cd beanquery-mcpInstall dependencies
Install beancount and beanquery into the uv-managed environment so the server can parse and query your ledger.
uv pip install beancount beanquerySet the ledger path and install the MCP server
Register the server with your MCP client using the uv mcp install command, passing the path to your .bean file as an environment variable.
uv run mcp install server.py -v BEANCOUNT_LEDGER=/absolute/path/to/your/ledger.bean --with beancount --with beanqueryAlternatively, configure via .env file
Create a .env file in the project root with BEANCOUNT_LEDGER set, then install referencing that file.
echo 'BEANCOUNT_LEDGER=/absolute/path/to/ledger.bean' > .env
uv run mcp install server.py -f .env --with beancount --with beanqueryVerify the server is available
Open your MCP client (e.g., Claude Desktop) and confirm that the beanquery server appears in the connected servers list. You can also call the set_ledger_file tool at runtime to switch ledger files.
Beancount Query Examples
Client configuration
Example claude_desktop_config.json entry for Beanquery MCP Server using uv run.
{
"mcpServers": {
"beanquery": {
"command": "uv",
"args": ["run", "--with", "beancount", "--with", "beanquery", "mcp", "run", "/absolute/path/to/beanquery-mcp/server.py"],
"env": {
"BEANCOUNT_LEDGER": "/absolute/path/to/your/ledger.bean"
}
}
}
}Prompts to try
Sample prompts to use once the server is connected in your MCP client.
- "What are all my expense accounts and their balances for this year?"
- "Run a BQL query: SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY account"
- "List all accounts in my ledger"
- "What tables can I query in my Beancount ledger?"
- "Show me all transactions from my checking account in the last 3 months"Troubleshooting Beancount Query
Server fails with 'BEANCOUNT_LEDGER not set' or cannot find the ledger file
Ensure the BEANCOUNT_LEDGER env var is set to an absolute (not relative) path. Double-check the path with 'ls /absolute/path/to/ledger.bean' before starting the server.
BQL query returns an error or unexpected results
Verify your Beancount ledger parses cleanly by running 'bean-check /path/to/ledger.bean'. Syntax errors in the ledger will prevent queries from running.
beancount or beanquery module not found when starting the server
Run 'uv pip install beancount beanquery' inside the project directory, or pass '--with beancount --with beanquery' to the uv run command so uv fetches them automatically.
Frequently Asked Questions about Beancount Query
What is Beancount Query?
Beancount Query is a Model Context Protocol (MCP) server that 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. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Beancount Query?
Follow the installation instructions on the Beancount Query GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Beancount Query?
Beancount Query works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Beancount Query free to use?
Yes, Beancount Query is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
Beancount Query Alternatives — Similar Finance & Fintech Servers
Looking for alternatives to Beancount Query? Here are other popular finance & fintech servers you can use with Claude, Cursor, and VS Code.
ValueCell
★ 10.7kValueCell is a community-driven, multi-agent platform for financial applications.
Vibe Trading
★ 8.1k'Vibe-Trading: Your Personal Trading Agent'
Quantdinger
★ 6.2kAI quantitative trading platform for crypto, stocks, and forex with backtesting, live trading, market data, and multi-agent research.vibe-trading ,trading-agents,ai-trader,ai-trading
TradingView
★ 2.8kReal-time crypto & stock screening, advanced technical indicators, Bollinger Bands intelligence, candlestick patterns + native Claude Desktop integration. Multi-exchange (Binance, KuCoin, Bybit+). Open-source AI trading infrastructure.
Financial Datasets
★ 2.1kProvides access to comprehensive financial data including income statements, balance sheets, cash flow statements, stock prices, company news, SEC filings, and cryptocurrency information with built-in financial ratio analysis.
Stripe
★ 1.6kThe Stripe Model Context Protocol server allows you to integrate with Stripe APIs through function calling. This protocol supports various tools to interact with different Stripe services.
Browse More Finance & Fintech MCP Servers
Explore all finance & fintech servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Beancount Query in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Beancount Query?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.