Learn FastMCP - MCP Server Examples

A learning project demonstrating how to build Model Context Protocol (MCP) servers using FastMCP, a Python framework for creating MCP-compatible tools and resources.

About This Project

This repository contains two complete MCP server implementations:

• Demo Server - Simple examples to learn FastMCP basics

• Expense Tracker - A full-featured real-world application

Perfect for understanding how to build MCP servers that can be used with Claude, other AI models, or custom applications.

Related MCP server: expense-tracker-mcp-server

📋 Server 1: Demo Server (main.py)

A simple starter MCP server with basic tools.

Tools

roll_dice(n_dice: int) -> list[int]

Rolls n six-sided dice and returns the results.

roll_dice(3) → [4, 2, 6]

add_numbers(a: float, b: float) -> float

Adds two numbers and returns the sum.

add_numbers(5, 3) → 8

Running the Demo Server

python main.py

💰 Server 2: Expense Tracker (test.py)

A comprehensive expense management MCP server with database persistence, categorization, and advanced filtering.

Features

• SQLite database for persistent storage

• Hierarchical category system (main category + subcategory)

• Date range filtering

• Expense summarization by category

• CRUD operations (Create, Read, Update, Delete)

• Category merging/renaming

Data Structure

Each expense entry contains:

• id - Unique identifier (auto-increment)

• date - Expense date (string format)

• amount - Expense amount in numeric value

• category - Main category (from categories.json)

• subcategory - Optional subcategory for detailed tracking

• note - Optional description/notes

Available Categories

The expense tracker supports 12 main categories with multiple subcategories each:

• Food - groceries, dining out, coffee, etc.

• Transport - fuel, public transport, cab/ride-hailing, parking, tolls

• Housing - rent, maintenance, property tax, repairs, furnishing

• Utilities - electricity, water, gas, internet, mobile, TV

• Health - medicines, doctor consultation, diagnostics, fitness

• Education - books, courses, online subscriptions, exam fees

• Family & Kids - school fees, daycare, toys, events

• Entertainment - movies, streaming subscriptions, gaming, outings

• Shopping - clothing, footwear, electronics, appliances, home décor

• Subscriptions - SaaS tools, cloud/AI, music, storage, newsletters

• Personal Care - salon, grooming, cosmetics, hygiene

• Gifts & Donations - personal gifts, charity, festival gifts

• Finance & Fees - bank fees, investment fees, etc.

Tools

add_expense(date: str, amount: int, category: str, subcategory: str = "", note: str = "")

Add a new expense entry to the database.

{
  "date": "2026-08-20",
  "amount": 45,
  "category": "food",
  "subcategory": "dining_out",
  "note": "Lunch with friends"
}

Returns: {"status": "ok", "id": 1}

list_expenses(start_date: str, end_date: str)

List all expenses within an inclusive date range (YYYY-MM-DD format).

list_expenses("2026-08-01", "2026-08-31")

Returns array of expense records with all fields.

summarize(start_date: str, end_date: str, category: str = None)

Get total amount spent by category within a date range. Optionally filter by a specific category.

summarize("2026-08-01", "2026-08-31")
summarize("2026-08-01", "2026-08-31", "food")

Returns:

[
  {"category": "food", "total_amount": 150},
  {"category": "transport", "total_amount": 50}
]

update_expense(id: int, date: str = None, amount: float = None, category: str = None, subcategory: str = None, note: str = None)

Update specific fields of an existing expense. Only provided fields are modified.

update_expense(1, amount=50, note="Updated note")

Returns: {"status": "ok", "id": 1, "updated_fields": {...}}

delete_expense(id: int)

Delete an expense entry by id.

delete_expense(1)

Returns: {"status": "ok", "deleted_id": 1}

merge_categories(old_categories: list[str], new_category: str)

Rename or merge one or more category labels into a single new category. Useful for consolidating expense categories.

merge_categories(["food", "dining"], "meals")

Returns: {"status": "ok", "rows_updated": 15, "new_category": "meals"}

Resources

expense://categories

Returns the categories structure as JSON. This resource is read fresh each time, so you can edit categories.json without restarting the server.

Running the Expense Tracker

python test.py

Database: Creates expenses.db in the same directory for persistent storage.

Installation & Setup

Prerequisites

• Python 3.14+

• FastMCP 3.4.7+

Install Dependencies

pip install fastmcp>=3.4.7

Or using the project's pyproject.toml:

pip install -e .

Project Structure

learn-fastmcp/
├── main.py              # Demo server (roll_dice, add_numbers)
├── test.py              # Expense Tracker server (full MCP implementation)
├── categories.json      # Category definitions for expense tracker
├── expenses.db          # SQLite database (auto-created by test.py)
├── pyproject.toml       # Project configuration
└── README.md            # This file

Learning Path

1. Start with main.py to understand the basics:

   • How to create a FastMCP instance

   • How to define simple tools with @mcp.tool decorator

   • How to run the server with mcp.run()

2. Progress to test.py to learn advanced patterns:

   • SQLite database integration

   • File I/O and resource management

   • Complex tool logic (CRUD operations)

   • Resources with @mcp.resource decorator

   • Optional and conditional parameters

   • Error handling and validation

Key FastMCP Concepts

Tools

Functions decorated with @mcp.tool() that can be called by MCP clients. Each tool has:

• Input parameters with type hints

• A docstring describing functionality

• A return value

Resources

Static or dynamic content accessible via URI. Defined with @mcp.resource():

• Identified by a unique URI (e.g., expense://categories)

• Optionally specify MIME type

• Can read from files or compute dynamically

Server Lifecycle

mcp = FastMCP("ServerName")  # Create instance

@mcp.tool()                  # Define tools
def my_tool(): ...

if __name__ == "__main__":
    mcp.run()               # Start the server

Next Steps

• Modify the demo server to add new tools

• Extend the expense tracker with new features (e.g., budgets, recurring expenses)

• Create your own MCP server for a domain you're interested in

• Connect your MCP server to Claude using the MCP protocol

Resources

• MCP Documentation

• FastMCP GitHub

• Python Typing Documentation

Happy learning! 🚀