EzBookkeeping MCP Server

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

1. Clone the repository:

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

2. Install dependencies:

uv sync

3. Configure (for full EzBookkeeping integration):

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

4. 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.