使用说明

Expense Tracker MCP Server

A Model Context Protocol (MCP) server for tracking and managing expenses using SQLite database. This tool provides MCP-compatible endpoints for adding and listing expenses.

Features

Add Expenses: Record expenses with date, amount, category, subcategory, and notes
List Expenses: Query expenses with optional filtering by category and limit
SQLite Database: Local SQLite database for persistent storage
MCP Compatible: Works with any MCP client

Prerequisites

Python 3.13 or higher
uv package manager (recommended) or pip

Installing uv

macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Ubuntu/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or using pip:

pip install uv

Installation

Step 1: Clone the Repository

git clone <repository-url>
cd expense

Step 2: Install Dependencies

Using uv (Recommended):

uv sync

Using pip:

pip install -e .

Or if you have a virtual environment:

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

Running the Server

Using uv (Recommended)

uv run python main.py

Using Python directly

If you've installed dependencies with pip:

python main.py

Or on some systems:

python3 main.py

The server will start and listen for MCP protocol messages via stdio.

Available Tools

1. `add_expense`

Add a new expense to the database.

Parameters:

date (str, required): Date in YYYY-MM-DD format
amount (float, required): Expense amount
category (str, required): Expense category
subcategory (str, optional): Subcategory
note (str, optional): Additional notes

Example:

{
  "date": "2024-01-27",
  "amount": 25.50,
  "category": "Food",
  "subcategory": "Groceries",
  "note": "Weekly shopping"
}

2. `list_expenses`

List expenses from the database.

Parameters:

limit (int, optional): Maximum number of expenses to return
category (str, optional): Filter by category

Example:

{
  "limit": 10,
  "category": "Food"
}

Database

The application uses SQLite database stored as expenses.db in the project directory.

Database Schema

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

The database is automatically created on first run.

Platform-Specific Notes

macOS

Python 3.13+ can be installed via Homebrew: brew install python@3.13
Ensure uv is in your PATH after installation

Windows

Install Python 3.13+ from python.org
During installation, check "Add Python to PATH"
Use PowerShell or Command Prompt for running commands
For uv, you may need to restart your terminal after installation

Ubuntu/Linux

Install Python 3.13+:

sudo apt update
sudo apt install python3.13 python3.13-venv python3-pip

Or use pyenv for Python version management

Troubleshooting

ModuleNotFoundError: No module named 'fastmcp'

Solution: Make sure dependencies are installed:

uv sync
# or
pip install -e .

Python version error

Solution: Ensure Python 3.13+ is installed:

python --version  # or python3 --version

If you have an older version, install Python 3.13+ or update requires-python in pyproject.toml.

Database permission errors

Solution: Ensure the project directory has write permissions for creating expenses.db.

uv command not found

Solution:

Restart your terminal after installing uv
Add ~/.cargo/bin to your PATH (Linux/macOS)
On Windows, uv is typically added to PATH automatically

Development

Project Structure

expense/
├── main.py           # Main application file
├── pyproject.toml    # Project configuration and dependencies
├── uv.lock          # Dependency lock file (uv)
├── expenses.db      # SQLite database (created on first run)
└── README.md        # This file

Adding New Tools

To add new MCP tools, use the @mcp.tool decorator:

@mcp.tool
def my_new_tool(param: str) -> dict:
    """Tool description."""
    # Your implementation
    return {"result": "success"}

License

[Add your license here]

Contributing

[Add contribution guidelines here]

Open the localhost of MCP server uv run fastmcp dev main.py Run the server v run fastmcp run main.py Install our server in Claude desktop uv run fastmcp install claude-desktop main.py

Then our created server tools will appear in the Claude desktop