MCP 服务器

ExpenseTracker MCP Server

Enables AI assistants to manage personal expenses by adding, querying, and summarizing expense data through a SQLite database and configurable categories.

README

ExpenseTracker MCP Server

A Model Context Protocol (MCP) server for managing personal expenses. Built with FastMCP, this server provides tools for tracking, querying, and summarizing expenses through an AI-ready interface.

Overview

ExpenseTracker is a lightweight MCP server that enables Claude and other AI applications to:

Add expenses to a SQLite database with categories and notes
Query expenses by date range for review and analysis
Summarize expenses by category to understand spending patterns
Manage categories through a configurable JSON file

This project demonstrates how to build a practical MCP server that integrates with AI assistants for real-world expense management.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI applications to interact with local tools and data sources safely. MCP servers expose resources and tools that AI models can access through a standardized interface, enabling features like:

Tool use and automation
Resource access and management
Server-side processing with client-side oversight

Learn more at modelcontextprotocol.io

Features

📊 Add Expenses - Log expenses with date, amount, category, subcategory, and notes
🔍 Query Expenses - Retrieve expenses within a date range with full filtering
💰 Summarize Spending - Get expense totals by category for budget analysis
📁 Category Management - Maintain a flexible list of expense categories via JSON
🗄️ SQLite Backend - Persistent storage with no external dependencies
🤖 MCP Integration - Works seamlessly with Claude and other MCP-compatible clients

Installation

Prerequisites

Python 3.14+
pip or uv package manager

Setup

Clone the repository

git clone https://github.com/yourusername/local-mcp-server.git
cd local-mcp-server

Create a virtual environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies
```
pip install -e .
# Or with uv:
uv sync
```

Create categories file (optional)

cat > categories.json << 'EOF'
{
  "categories": [
    "Food & Dining",
    "Transportation",
    "Entertainment",
    "Shopping",
    "Bills & Utilities",
    "Health & Fitness",
    "Travel",
    "Other"
  ]
}
EOF

Usage

Running the Server

Start the MCP server:

python main.py

The server will initialize the SQLite database and listen for MCP connections.

Available Tools

`add_expense`

Add a new expense entry to the database.

Parameters:

date (string, required): Date in YYYY-MM-DD format
amount (number, required): Expense amount
category (string, required): Expense category
subcategory (string, optional): Subcategory for detailed tracking
note (string, optional): Additional notes or description

Example:

{
  "date": "2024-06-14",
  "amount": 45.50,
  "category": "Food & Dining",
  "subcategory": "Restaurant",
  "note": "Lunch at Italian place"
}

`list_expenses`

Retrieve expenses within a date range.

Parameters:

start_date (string, required): Start date in YYYY-MM-DD format (inclusive)
end_date (string, required): End date in YYYY-MM-DD format (inclusive)

Example:

{
  "start_date": "2024-06-01",
  "end_date": "2024-06-30"
}

Returns: Array of expense objects with id, date, amount, category, subcategory, and note fields.

`summarize`

Get a summary of expenses by category within a date range.

Parameters:

start_date (string, required): Start date in YYYY-MM-DD format (inclusive)
end_date (string, required): End date in YYYY-MM-DD format (inclusive)
category (string, optional): Filter by specific category

Example:

{
  "start_date": "2024-06-01",
  "end_date": "2024-06-30",
  "category": "Food & Dining"
}

Returns: Array of category summary objects with category and total_amount fields.

Resources

`expense://categories`

Access the current list of expense categories. The categories file is read fresh on each access, allowing modifications without server restart.

MIME Type: application/json

Configuration

Database

The SQLite database file is stored as expenses.db in the project root. The database is automatically initialized on first run with the expenses table.

Schema:

CREATE TABLE expenses(
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  date TEXT NOT NULL,
  amount REAL NOT NULL,
  category TEXT NOT NULL,
  subcategory TEXT DEFAULT '',
  note TEXT DEFAULT ''
)

Project Structure

local-mcp-server/
├── main.py              # MCP server implementation
├── expenses.db          # SQLite database (auto-created)
├── categories.json      # Category definitions
├── pyproject.toml       # Project configuration
├── uv.lock             # Dependency lock file
├── LICENSE             # GPL 3.0 license
└── README.md           # This file

Technical Details

Framework: FastMCP
Database: SQLite3 (built-in Python library)
Protocol: Model Context Protocol (MCP)
Language: Python 3.14+

Integration with Claude

To use this server with Claude or other MCP clients, configure your client to connect to this server. Consult your client's documentation for MCP server setup instructions.