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.

---

📋 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! 🚀