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 beanqueryConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Beancount Query
The Beanquery MCP server connects AI assistants directly to Beancount plaintext accounting ledger files, enabling natural language queries against financial data using Beancount Query Language (BQL). It exposes tools for executing BQL queries and browsing account structures, so you can ask an AI to analyze spending, summarize balances, or audit transactions without leaving your chat interface. This is especially valuable for developers and accountants who maintain ledgers in Beancount and want AI-assisted financial analysis without exporting data.
Prerequisites
- Python 3.10+ installed
- uv package manager installed (https://github.com/astral-sh/uv)
- Beancount ledger file (.bean) available on disk
- An MCP-compatible client such as Claude Desktop or Cursor
Clone the repository
Clone the beanquery-mcp repository to your local machine so you have the server.py and dependencies available.
git clone https://github.com/vanto/beanquery-mcp.git
cd beanquery-mcpInstall dependencies with uv
Use uv to install the required beancount and beanquery Python packages that the server depends on.
uv pip install beancount beanquerySet the BEANCOUNT_LEDGER environment variable
The server requires a BEANCOUNT_LEDGER environment variable pointing to your .bean ledger file. You can set it inline or via a .env file.
export BEANCOUNT_LEDGER=/path/to/your/ledger.beanInstall the server into Claude Desktop
Use uv run mcp install to register the server with Claude Desktop, supplying the ledger path and required packages.
uv run mcp install server.py -v BEANCOUNT_LEDGER=/path/to/your/ledger.bean \
--with beancount --with beanqueryVerify server startup
Test the server in development mode to confirm it loads the ledger and exposes the BQL tools correctly.
mcp dev server.pyBeancount Query Examples
Client configuration
Add to your claude_desktop_config.json to register the beanquery MCP server with the path to your ledger file.
{
"mcpServers": {
"beanquery": {
"command": "uv",
"args": ["run", "server.py"],
"env": {
"BEANCOUNT_LEDGER": "/path/to/your/ledger.bean"
}
}
}
}Prompts to try
Example queries you can send to your AI assistant once the beanquery server is connected.
- "Run a BQL query to show my total expenses by category for 2024"
- "List all accounts in my Beancount ledger"
- "What tables are available to query in my ledger?"
- "Show me all transactions in the Expenses:Food account from last month"Troubleshooting Beancount Query
Server fails to start with 'BEANCOUNT_LEDGER not set' error
Ensure the BEANCOUNT_LEDGER environment variable is set to the absolute path of your .bean file, either in the env block of the MCP config or exported in your shell before running the install command.
BQL queries return parse errors
Beancount Query Language has specific syntax — ensure field names and table names match your ledger structure. Use the beanquery://tables resource to see available tables and beanquery://accounts to see account names before writing queries.
beancount or beanquery packages not found
Pass --with beancount --with beanquery to the uv run mcp install command, or install them manually with uv pip install beancount beanquery in the project directory.
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. 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.