EzBookkeeping MCP Server

![License: MIT](https://opensource.org/licenses/MIT) ![Python 3.10+](https://www.python.org/downloads/) ![MCP](https://modelcontextprotocol.io)

A comprehensive Model Context Protocol (MCP) server that integrates AI assistants with EzBookkeeping, enabling natural language interactions for personal finance management.

Note: This project is currently in active development. The server currently includes example/demo implementations. Full integration with the EzBookkeeping API is planned based on the comprehensive research documented in this repository.

What is This?

This MCP server allows AI assistants like Claude to interact with your EzBookkeeping instance through natural language. Ask Claude to add transactions, check balances, analyze spending patterns, and generate financial reports - all through conversation.

Example interactions:

"Add a $45 grocery expense to my checking account"
"Show me my spending trends for this month"
"What's my total balance across all accounts?"
"Create a budget report for the last quarter"

Features

Current (Demo Implementation)

Tools (Write Operations):

add_transaction - Add income or expense transactions
calculate_balance - Calculate balance from transaction lists

Resources (Read Operations):

bookkeeping://summary/{period} - Get financial summary for a period

Prompts (AI Templates):

create_financial_report - Generate financial report prompts

Planned (Full EzBookkeeping Integration)

Based on comprehensive API research (99 endpoints documented):

Transaction Management:

Create, update, delete transactions
Batch operations
AI-powered receipt recognition
Transaction statistics and trends
Import/export functionality

Account Management:

Manage accounts across 9 types (Cash, Credit Card, Investment, etc.)
Multi-currency support
Hierarchical accounts with sub-accounts

Organization:

Category and tag management
Transaction templates
Recurring transactions

Analytics:

Spending analysis and trends
Budget tracking
Financial summaries and reports

See MCP_SERVER_DESIGN.md for the complete architecture plan.

Installation

Prerequisites

Python 3.10 or higher
uv package manager
(Optional) An EzBookkeeping instance for full API integration

Quick Start

Clone the repository:

git clone https://github.com/theanirudhvyas/ezbookkeeping_mcp_server.git
cd ezbookkeeping_mcp_server

Install dependencies:

uv sync

Configure (for full EzBookkeeping integration):

cp .env.example .env
# Edit .env with your EzBookkeeping instance URL and API token

Test the server:

uv run mcp dev main.py

This opens the MCP Inspector at http://localhost:5173 for interactive testing.

Configuration

For full EzBookkeeping API integration, configure the following environment variables:

# Required
EZBOOKKEEPING_URL=https://your-instance.com
EZBOOKKEEPING_TOKEN=your_api_token_here

# Optional
EZBOOKKEEPING_TIMEZONE_OFFSET=0
EZBOOKKEEPING_DEFAULT_CURRENCY=USD

See .env.example for a complete configuration template.

Usage with Claude Desktop

Automatic Installation

uv run mcp install main.py

Manual Configuration

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ezbookkeeping": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ezbookkeeping_mcp_server",
        "run",
        "mcp",
        "run",
        "main.py"
      ],
      "env": {
        "EZBOOKKEEPING_URL": "https://your-instance.com",
        "EZBOOKKEEPING_TOKEN": "your_token"
      }
    }
  }
}

Restart Claude Desktop to load the server.

Development

Running the MCP Inspector

The MCP Inspector provides an interactive web interface for testing:

uv run mcp dev main.py

Opens at http://localhost:5173 with:

Tool testing with parameter forms
Resource browsing
Prompt generation
Real-time request/response logs

Running Tests

# Install dev dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=. --cov-report=html

Usage Examples

Adding a Transaction

# Using the add_transaction tool
add_transaction(
    amount=50.00,
    description="Grocery shopping",
    category="food",
    transaction_type="expense"
)

Calculating Balance

# Using the calculate_balance tool
transactions = [
    {"amount": 1000, "type": "income"},
    {"amount": 50, "type": "expense"},
    {"amount": 30, "type": "expense"}
]
calculate_balance(transactions)
# Returns: {"income": 1000, "expenses": 80, "balance": 920}

Getting a Summary

Access the resource URI: `` bookkeeping://summary/month ``

Project Structure

ezbookkeeping_mcp_server/
├── main.py                    # MCP server implementation
├── pyproject.toml             # Project configuration & dependencies
├── API_DOCUMENTATION.md       # Complete EzBookkeeping API reference (99 endpoints)
├── MCP_SERVER_DESIGN.md       # Architecture and implementation plan
├── QUICKSTART.md              # Quick reference guide
├── README.md                  # This file
├── CONTRIBUTING.md            # Contribution guidelines
├── CHANGELOG.md               # Version history
├── LICENSE                    # MIT License
├── .env.example               # Environment configuration template
├── .claude/                   # Claude Code configuration
│   └── CLAUDE.md              # MCP development best practices
├── tests/                     # Test suite (planned)
└── .venv/                     # Virtual environment (gitignored)

Documentation

API_DOCUMENTATION.md - Complete EzBookkeeping API reference with all 99 endpoints
MCP_SERVER_DESIGN.md - Comprehensive architecture, design decisions, and roadmap
QUICKSTART.md - Quick start guide for common operations
.claude/CLAUDE.md - MCP server development best practices

Roadmap

Phase 1: Foundation (Planned)

[ ] HTTP client with authentication
[ ] Token management and refresh
[ ] Error handling and retry logic
[ ] Timezone support

Phase 2: Core Features (Planned)

[ ] Transaction tools (add, update, delete)
[ ] Account resources (list, get)
[ ] Transaction resources (list, statistics)
[ ] Category/tag resources

Phase 3: Advanced Features (Planned)

[ ] Batch operations
[ ] Transaction templates
[ ] AI receipt recognition integration
[ ] Export functionality
[ ] Exchange rate management

Phase 4: Intelligence (Planned)

[ ] Spending analysis prompts
[ ] Budget tracking prompts
[ ] Financial insights generation
[ ] Duplicate detection
[ ] Category suggestions

See MCP_SERVER_DESIGN.md for detailed implementation plan.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Areas for Contribution

Implementing API endpoints
Adding tests
Improving error handling
Documentation improvements
Feature suggestions

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
EzBookkeeping: Official Documentation

Related Projects

EzBookkeeping - The personal bookkeeping application
Model Context Protocol - MCP specification and documentation
Python MCP SDK - Official Python SDK

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

EzBookkeeping by @mayswind for the excellent personal finance application
Model Context Protocol by Anthropic for the integration framework
The MCP community for tools and resources

Disclaimer

This project is not officially affiliated with or endorsed by the EzBookkeeping project. It is an independent integration built using EzBookkeeping's public HTTP API.

EzBookkeeping MCP Server