Lerne FastMCP - MCP-Server-Beispiele

Ein Lernprojekt, das zeigt, wie man Model Context Protocol (MCP)-Server mit FastMCP erstellt, einem Python-Framework für die Entwicklung MCP-kompatibler Tools und Ressourcen.

Über dieses Projekt

Dieses Repository enthält zwei vollständige MCP-Server-Implementierungen:

• Demo-Server - Einfache Beispiele, um die FastMCP-Grundlagen zu erlernen

• Ausgabenrechner - Eine voll ausgestattete Praxis-Anwendung

Perfekt, um zu verstehen, wie man MCP-Server erstellt, die mit Claude, anderen KI-Modellen oder eigenen Anwendungen verwendet werden können.

Related MCP server: expense-tracker-mcp-server

📋 Server 1: Demo-Server (main.py)

Ein einfacher Einstiegs-MCP-Server mit grundlegenden Tools.

Tools

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

Würfelt mit n sechsseitigen Würfeln und gibt die Ergebnisse zurück.

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

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

Addiert zwei Zahlen und gibt die Summe zurück.

add_numbers(5, 3) → 8

Den Demo-Server ausführen

python main.py

💰 Server 2: Ausgabenrechner (test.py)

Ein umfassender MCP-Server zur Ausgabenverwaltung mit Datenbank-Persistenz, Kategorisierung und erweiterten Filtermöglichkeiten.

Funktionen

• SQLite-Datenbank für dauerhafte Speicherung

• Hierarchisches Kategoriesystem (Hauptkategorie + Unterkategorie)

• Datumsbereichsfilterung

• Ausgabenzusammenfassung nach Kategorie

• CRUD-Operationen (Erstellen, Lesen, Aktualisieren, Löschen)

• Kategorien zusammenführen/umbenennen

Datenstruktur

Jeder Ausgabeneintrag enthält:

• id - Eindeutige Kennung (automatisch inkrementiert)

• date - Ausgabedatum (Zeichenkettenformat)

• amount - Ausgabenbetrag als numerischer Wert

• category - Hauptkategorie (aus categories.json)

• subcategory - Optionale Unterkategorie für detaillierte Erfassung

• note - Optionale Beschreibung/Notizen

Verfügbare Kategorien

Der Ausgabenrechner unterstützt 12 Hauptkategorien mit jeweils mehreren Unterkategorien:

• Lebensmittel - Lebensmittel, Restaurantbesuche, Kaffee usw.

• Verkehr - Kraftstoff, öffentliche Verkehrsmittel, Taxi/Fahrdienste, Parken, Maut

• Wohnen - Miete, Instandhaltung, Grundsteuer, Reparaturen, Einrichtung

• Nebenkosten - Strom, Wasser, Gas, Internet, Mobilfunk, Fernsehen

• Gesundheit - Medikamente, Arztbesuche, Diagnostik, Fitness

• Bildung - Bücher, Kurse, Online-Abonnements, Prüfungsgebühren

• Familie & Kinder - Schulgebühren, Kinderbetreuung, Spielzeug, Veranstaltungen

• Unterhaltung - Kino, Streaming-Abonnements, Gaming, Ausflüge

• Einkaufen - Kleidung, Schuhe, Elektronik, Haushaltsgeräte, Wohndekoration

• Abonnements - SaaS-Tools, Cloud/KI, Musik, Speicher, Newsletter

• Körperpflege - Friseur, Pflege, Kosmetik, Hygiene

• Geschenke & Spenden - persönliche Geschenke, Spenden, Festtagsgeschenke

• Finanzen & Gebühren - Bankgebühren, Anlagegebühren usw.

Tools

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

Einen neuen Ausgabeneintrag zur Datenbank hinzufügen.

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

Gibt zurück: {"status": "ok", "id": 1}

list_expenses(start_date: str, end_date: str)

Alle Ausgaben innerhalb eines inklusiven Datumsbereichs auflisten (Format JJJJ-MM-TT).

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

Gibt ein Array von Ausgabendatensätzen mit allen Feldern zurück.

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

Gesamtbetrag der Ausgaben nach Kategorie innerhalb eines Datumsbereichs abrufen. Optional kann nach einer bestimmten Kategorie gefiltert werden.

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

Gibt zurück:

[
  {"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)

Bestimmte Felder eines vorhandenen Ausgabeneintrags aktualisieren. Es werden nur die angegebenen Felder geändert.

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

Gibt zurück: {"status": "ok", "id": 1, "updated_fields": {...}}

delete_expense(id: int)

Einen Ausgabeneintrag anhand der ID löschen.

delete_expense(1)

Gibt zurück: {"status": "ok", "deleted_id": 1}

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

Eine oder mehrere Kategoriebezeichnungen in eine einzige neue Kategorie umbenennen oder zusammenführen. Nützlich zum Konsolidieren von Ausgabenkategorien.

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

Gibt zurück: {"status": "ok", "rows_updated": 15, "new_category": "meals"}

Ressourcen

expense://categories

Gibt die Kategoriestruktur als JSON zurück. Diese Ressource wird bei jedem Zugriff neu gelesen, sodass Sie categories.json bearbeiten können, ohne den Server neu zu starten.

Den Ausgabenrechner ausführen

python test.py

Datenbank: Erstellt expenses.db im selben Verzeichnis für die dauerhafte Speicherung.

Installation & Einrichtung

Voraussetzungen

• Python 3.14+

• FastMCP 3.4.7+

Abhängigkeiten installieren

pip install fastmcp>=3.4.7

Oder mit der pyproject.toml des Projekts:

pip install -e .

Projektstruktur

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

Lernpfad

1. Beginnen Sie mit main.py, um die Grundlagen zu verstehen:

   • Wie man eine FastMCP-Instanz erstellt

   • Wie man einfache Tools mit dem @mcp.tool-Dekorator definiert

   • Wie man den Server mit mcp.run() ausführt

2. Fahren Sie mit test.py fort, um fortgeschrittene Muster zu erlernen:

   • SQLite-Datenbankanbindung

   • Datei-E/A und Ressourcenverwaltung

   • Komplexe Tool-Logik (CRUD-Operationen)

   • Ressourcen mit dem @mcp.resource-Dekorator

   • Optionale und bedingte Parameter

   • Fehlerbehandlung und Validierung

Wichtige FastMCP-Konzepte

Tools

Funktionen, die mit @mcp.tool() dekoriert sind und von MCP-Clients aufgerufen werden können. Jedes Tool hat:

• Eingabeparameter mit Typannotationen

• Einen Docstring, der die Funktionalität beschreibt

• Einen Rückgabewert

Ressourcen

Statische oder dynamische Inhalte, die über eine URI zugänglich sind. Werden mit @mcp.resource() definiert:

• Durch eine eindeutige URI gekennzeichnet (z. B. expense://categories)

• Optional kann ein MIME-Typ angegeben werden

• Kann aus Dateien lesen oder dynamisch berechnet werden

Server-Lebenszyklus

mcp = FastMCP("ServerName")  # Create instance

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

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

Nächste Schritte

• Den Demo-Server anpassen, um neue Tools hinzuzufügen

• Den Ausgabenrechner um neue Funktionen erweitern (z. B. Budgets, wiederkehrende Ausgaben)

• Einen eigenen MCP-Server für einen Bereich erstellen, der Sie interessiert

• Ihren MCP-Server über das MCP-Protokoll mit Claude verbinden

Ressourcen

• MCP-Dokumentation

• FastMCP GitHub

• Python-Typisierungsdokumentation

Viel Spaß beim Lernen! 🚀