MCP-Server mit FastMCP erstellen: Python-Anleitung mit Beispielen

Inhalt

Ein MCP-Server stellt Ihre Daten und Tools für LLM-Anwendungen bereit, und zwar über das Model Context Protocol (MCP), einen Standard, um LLMs mit externen Ressourcen zu verbinden. FastMCP ist ein Python-Framework, das gewöhnliche Funktionen mit ein paar Decorators in MCP-Resources und -Tools verwandelt. Jeder MCP-fähige Client (etwa Claude Desktop) kann sie dann sofort nutzen.

Diese Anleitung erklärt, was ein MCP-Server ist und worin er sich von einer normalen API unterscheidet. Danach bauen wir mit FastMCP einen: mit einer Resource, einem Resource Template, einem Tool mit Parameter-Metadaten, Fortschrittsmeldungen und einem kleinen Test-Client.

Man kann sich MCP wie einen USB-C-Anschluss für KI-Anwendungen vorstellen: ein Stecker, über den Sprachmodelle mit wenig Aufwand an verschiedene Datenquellen und Tools angeschlossen werden.

Was ist ein MCP-Server?

Ein MCP-Server ist ein schlankes Programm, das Ihre Daten und Funktionen über das standardisierte Model Context Protocol für Sprachmodelle bereitstellt. Er sitzt zwischen KI-Anwendungen (wie Claude Desktop oder anderen LLM-basierten Tools) und Ihren lokalen Datenquellen oder entfernten Diensten.

MCP hat sechs zentrale Bausteine:

1. Resources: lesende Endpunkte, die LLMs Daten liefern (ähnlich wie GET-Requests in Web-APIs)
2. Tools: Endpunkte, die eine Aktion ausführen, wenn ein LLM sie aufruft (ähnlich wie POST- oder PUT-Endpunkte)
3. Prompts: wiederverwendbare Vorlagen, die steuern, wie LLMs mit Ihrem Server arbeiten
4. Sampling: die Möglichkeit, beim verbundenen LLM eine Completion anzufordern. Braucht der Server für eine eigene Aktion ein LLM (etwa für eine Zusammenfassung), kann er den Client bitten, die Completion auszuführen. Der Client bezahlt sie dann und bestimmt, welches LLM zum Einsatz kommt, was für den Datenschutz wichtig ist. Ausführlich behandeln wir das in LLM Sampling mit FastMCP (auf Englisch).
5. Transports: die Kommunikationswege, über die Client und Server Nachrichten austauschen, etwa stdio (Standard Input/Output) für lokale Tools und SSE (Server-Sent Events) für webbasierte Anwendungen
6. Roots: URI-basierte Grenzen, die festlegen, wo ein Server arbeiten darf. Darüber teilen Clients dem Server mit, welche Ressourcen relevant sind (etwa Dateipfade oder API-Endpunkte).

MCP-Server arbeiten in einer Client-Server-Architektur:

• Ihr MCP-Server läuft lokal oder auf Ihrer Infrastruktur.
• MCP-Clients (wie Claude Desktop) verbinden sich mit Ihrem Server.
• Ihr Server gibt kontrollierten, sicheren Zugriff auf Ihre Dateien, Datenbanken, APIs oder eigene Funktionen.

Anders als klassische Web-APIs sind MCP-Server für die Arbeit mit LLMs gebaut, mit Kontextverwaltung und weiteren LLM-spezifischen Funktionen.

Über einen MCP-Server können KI-Assistenten mit Ihren Daten und Diensten arbeiten, während die Informationen sicher bei Ihnen und unter Ihrer Kontrolle bleiben. Sie müssen keine sensiblen Dokumente zu Drittanbietern hochladen und nicht für jedes neue KI-Tool die Integration neu bauen.

LLM-Anwendung mit MCP-Client, die sich mit einem MCP-Server verbindet

Beispiel: der GitHub-MCP-Server

Falls das abstrakt klingt, hier ein einfaches Beispiel. GitHub bietet einen MCP-Server mit Tools für die Arbeit mit GitHub an, etwa um Informationen zu einem Repository abzurufen oder Pull Requests anzulegen.

Viele KI-Chat-Tools bringen bereits einen MCP-Client mit. Sie alle können sich also mit GitHub verbinden und KI-gestützte Workflows darauf aufbauen. Davon profitieren beide Seiten. Die Tools müssen weder die GitHub-API noch viele andere APIs einzeln anbinden, sie implementieren nur den MCP-Client. Und weil LLMs über MCP die Liste der verfügbaren Tools lesen können, kennen sie automatisch jedes Tool (jeden "API-Endpunkt", wenn man so will).

Was ist der Unterschied zwischen einem MCP-Server und einer API?

Im Kern sind MCP-Server standardisierte APIs. Warum also nicht die Millionen bestehender APIs nutzen? Weil LLMs bei einem MCP-Server leicht herausfinden, welche Tools und Resources er anbietet. Außerdem standardisiert MCP Authentifizierung und Transport. Wenn sich genug Unternehmen auf MCP als gemeinsamen Weg einigen (und viele tun das bereits, etwa Microsoft, Anthropic, Google und OpenAI), gibt es eine einzige Schnittstelle, die darauf ausgelegt ist, dass LLMs sie selbst erkunden. Client-Tools müssen nur den MCP-Client implementieren, den Rest erledigen das Protokoll und die LLMs, die den Client nutzen. MCP ergibt allerdings nur dann wirklich Sinn, wenn ein LLM die angebotenen Resources und Tools "liest" und danach handelt.

Wenn Sie einfach nur APIs aufrufen müssen, sind normale REST-Endpunkte weiterhin die richtige Wahl.

MCP-Server haben noch einen Vorteil. Weil KI-Clients das Protokoll breit übernommen haben, können Sie auch einen lokalen MCP-Server betreiben, der kontrolliert und sicher auf Ressourcen Ihres Systems zugreift. Sie können zum Beispiel Zugriff auf das Dateisystem erlauben, aber nur auf ein bestimmtes Laufwerk.

Was ist FastMCP?

FastMCP ist ein High-Level-Framework in Python, mit dem Sie MCP-Server bauen. Wer das rohe MCP-Protokoll nutzt, muss Server-Setup, Protokoll-Handler, Content Types und Fehlerbehandlung selbst implementieren. FastMCP nimmt Ihnen all diese Details ab.

Kern von FastMCP ist eine Decorator-basierte API, die normale Python-Funktionen in MCP-kompatible Tools, Resources und Prompts verwandelt. Die wichtigsten Vorteile:

1. Wenig Boilerplate: Ein funktionierender MCP-Server braucht nur wenige Zeilen Code.
2. Das Decorator-Muster kennen Sie, wenn Sie schon mit Flask oder FastAPI gearbeitet haben.
3. Automatische Schema-Erzeugung: FastMCP erzeugt die MCP-Schemas aus Type Hints und Docstrings, ohne manuelle Konfiguration.
4. Pydantic-Integration: Komplexe Ein- und Ausgaben lassen sich als Pydantic-Modelle mit automatischer Validierung abbilden.
5. Eingebaute Unterstützung für synchrone und asynchrone Handler.
6. Abstrahierte Transports: Sie wechseln zwischen Protokollen (stdio, Streamable HTTP und dem älteren SSE-Transport), ohne Ihren Anwendungscode zu ändern.
7. Ein Context-Objekt, über das Sie auf Server-Funktionen zugreifen, loggen, Fortschritt melden und sogar LLM-Sampling anfordern.
8. Eine vollständige Client-Implementierung, mit der Sie Ihre Server programmatisch testen.

FastMCP will die MCP-Entwicklung für Python-Entwickler jeder Erfahrungsstufe zugänglich machen und trotzdem das komplette Protokoll abdecken. Sie kümmern sich um Ihre Geschäftslogik statt um die Details der MCP-Spezifikation.

Mit FastMCP kommen Sie in Minuten statt Stunden von der Idee zum funktionierenden MCP-Server. Deshalb ist es unsere Wahl, sowohl für Prototypen von KI-Tools als auch für produktive MCP-Dienste.

Praxis: einen MCP-Server mit FastMCP bauen

Wir bauen einen einfachen MCP-Server, der

• das Profil eines Benutzers abruft (Resource),
• ein Dokument auf dem Server ändert (Tool) und
• Fortschritt meldet (Context).

Voraussetzungen: das Grundgerüst des MCP-Servers

Legen Sie zuerst eine virtuelle Umgebung an und installieren Sie fastmcp (die MCP-Abhängigkeiten sind enthalten).

1uv venv
2source .venv/bin/activate
3uv pip install fastmcp

Dann erstellen Sie die Server-Instanz:

1from fastmcp import FastMCP
2
3mcp = FastMCP(
4    name="Document Assistant",
5    instructions="This server allows to fetch and update documents related to PONDHOUSE DATA DOCS."
6)
7
8if __name__ == "__main__":
9    mcp.run()

Dieses Snippet startet einen MCP-Server (noch ohne Resources) im STDIO-Transport. Das bedeutet:

• Der Client startet für jede Session einen neuen Serverprozess.
• Die Kommunikation läuft über Standard-Ein- und -Ausgabe.
• Der Serverprozess endet, wenn sich der Client trennt.
• Das passt gut zu lokalen Tools wie Claude Desktop, bei denen jedes Gespräch eine eigene Server-Instanz bekommt.

Die Transports von FastMCP

Der Server oben nutzt den STDIO-Transport und gibt damit vor allem Zugriff auf Ressourcen Ihres lokalen Systems. Dafür gibt es viele Anwendungsfälle, aber den größten Vorteil von MCP-Servern sehen wir im entfernten Zugriff: kontrollierter, sicherer Zugang zu Ihren internen Systemen. Dafür bietet FastMCP einen zweiten Transport: SSE Transport (Server Sent Events).

So nutzen Sie diesen Transport:

1mcp.run(transport="sse", host="0.0.0.0", port=8000)

Damit lauscht der Server auf allen Interfaces an Port 8000.

Ab hier verwenden wir diesen Transport.

Eine MCP-Resource mit FastMCP anlegen

MCP-Resources geben lesenden Zugriff auf interne Daten. Ein Client fordert eine Resource über ihre URI an (die auf Client-Seite oft von der KI erzeugt wird). FastMCP findet über die URI die passende Resource, holt die Daten und gibt sie an den Client zurück.

Eine Resource ist schnell definiert:

1. Schreiben Sie eine Python-Funktion, die die gewünschten Daten zurückgibt.

2. Versehen Sie sie mit dem Resource-Decorator von fastmcp und übergeben Sie die eindeutige URI der Resource als Parameter.

3. Ergänzen Sie optional Metadaten wie eine Beschreibung oder Tags.

   Hinweis: Clients können diese Metadaten zum Filtern nutzen oder um zu entscheiden, welche Resource sie aufrufen. Wie bei jeder LLM-Anwendung sind die Metadaten wichtig, damit die KI auf Client-Seite weiß, was zu tun ist. Wir empfehlen, sie immer vollständig auszufüllen.

   Diese Metadaten stehen zur Verfügung:

   • uri: die eindeutige Kennung der Resource (Pflicht).
   • name: ein lesbarer Name (Standard: der Funktionsname).
   • description: eine Beschreibung der Resource (Standard: der Docstring).
   • mime_type: der Content Type (FastMCP leitet oft einen Standardwert wie text/plain oder application/json ab, bei Nicht-Text-Typen ist eine explizite Angabe besser).
   • tags: eine Menge von Strings zur Kategorisierung, die Clients etwa zum Filtern nutzen können.

1from fastmcp import FastMCP
2
3mcp = FastMCP(
4    name="Document Assistant",
5    instructions="This server allows to fetch and update documents related to PONDHOUSE DATA DOCS."
6)
7
8@mcp.resource(
9    uri="data://application-information",
10    name="ApplicationInfo",
11    description="Provides general runtime-information about the application",
12    mime_type="application/json",
13    tags={"status", "observability"}
14)
15async def get_application_status() -> dict:
16    """Function description - ignored if set via decorator description parameter"""
17
18    # TODO: Hier beliebige Logik einbauen, z. B. eine Datenbankabfrage oder
19    # Statusinformationen aus Ihrem Monitoring-System.
20
21    return {
22          "app_id": 123,
23          "status": "running",
24          "started_at": "2025-04-27 10:23:00"
25     }

Bisher bekommt ein Client, der die URI data://application-information anfordert, den Status der Anwendung. Als Nächstes soll ein Benutzerprofil zurückkommen. Das Problem: Wir können dem MCP-Server noch keine Benutzer-ID übergeben, denn die URI ist das Einzige, was wir austauschen.

Hier kommen Resource Templates ins Spiel.

MCP Resource Templates

Mit Resource Templates teilen Sie dem MCP-Server mit, dass Teile des URI-Pfads in der Resource-Definition dynamisch sind. Für unser Benutzerprofil können wir zum Beispiel die URI data://user-profile/{user_id} festlegen. Die Resource-Funktion bekommt dann einen zusätzlichen Parameter für den dynamischen Wert.

1@mcp.resource(
2    uri="data://user-profile/{user_id}",
3    name="UserProfile",
4    description="Gets the user profile information for user_id",
5    mime_type="application/json",
6    tags={"user"}
7)
8async def get_user_profile(user_id: str) -> dict:
9    """Gets the user profile information for user_id"""
10
11    # TODO: Hier beliebige Logik einbauen, z. B. eine Datenbankabfrage oder
12    # Profildaten aus Ihrem Benutzer- und Anmeldesystem.
13
14    return {
15      "user_id": 1234,
16      "user_name": "Hans Maier",
17      "email": "hans@maier.com"
18     }

Jetzt fordern Clients die Resource mit einem dynamischen Parameter user_id an.

Ein MCP-Tool mit FastMCP anlegen

Tools sind der wichtigste Teil jedes KI-Agenten-Systems. Es sind Funktionen, über die die KI mit der Außenwelt arbeitet. Angenommen, Sie haben eine Funktion, die eine Datenbank abfragt. Machen Sie daraus ein tool, kann die KI sie aufrufen und damit auf Ihre Datenbank zugreifen. Unser Beitrag über einen MCP-Server für BigQuery zeigt dieses Muster mit einem echten Data Warehouse.

Eine ausführliche Einführung in Tools bietet unser Artikel KI-Agenten ohne Framework bauen (auf Englisch).

Wie bei Resources kümmert sich FastMCP um das Protokoll und darum, wer was aufruft. Sie schreiben eine Funktion, die etwas tut, setzen einen Decorator und ergänzen bei Bedarf Metadaten.

FastMCP

• verwendet den Funktionsnamen als Namen des Tools (wählen Sie ihn also aussagekräftig),
• verwendet den Docstring (oder den Parameter description im Decorator) als Beschreibung des Tools,
• erzeugt das Schema aus den Type Annotations und
• validiert eingehende Daten gegen dieses Schema.

Auch hier gilt: Schreiben Sie Tools asynchron, wenn sie auf I/O warten.

1@mcp.tool()
2async def edit_file(filename: str, line: str) -> None:
3    """
4    Asynchronously appends a line of text to the end of a file.
5    """
6    try:
7        async with aiofiles.open(filename, mode='a') as file:
8            if not line.endswith('\n'):
9                line += '\n'
10            await file.write(line)
11    except Exception as e:
12        print(f"Error appending to file: {str(e)}")
13        raise

Parameter-Metadaten ergänzen

Wer schon KI-Agenten (oder Clients) (auf Englisch) gebaut hat, weiß: Die Beschreibung des Tools ist das Wichtigste, und die Beschreibungen der Parameter sind noch wichtiger. Sie sagen der KI, welche Parameter sie liefern muss.

In FastMCP ergänzen Sie diese Informationen mit Field aus pydantic innerhalb von Annotated.

Parameter mit Standardwert werden als optional übermittelt.

1@mcp.tool()
2async def edit_file(
3    filename: Annotated[ str, Field( description="Path to the target file", min_length=1, max_length=255) ],
4    line: Annotated[ str, Field( description="Text content to append to the file", min_length=1) ],
5    second_line: Annotated[ str, Field( description="Optional second line to append to the file", min_length=1), ] = ""
6    ):
7    """
8    Asynchronously appends a line of text to the end of a file.
9    """
10    try:
11        async with aiofiles.open(filename, mode='a') as file:
12            if not line.endswith('\n'):
13                line += '\n'
14            await file.write(line)
15
16            if second_line:
17                if not second_line.endswith('\n'):
18                    second_line += '\n'
19                await file.write(second_line)
20    except Exception as e:
21        print(f"Error appending to file: {str(e)}")
22        raise

Fehlerbehandlung in FastMCP-Tools

Fehlt noch ein Baustein: Wie erfährt die KI von Fehlern? In der Regel soll die KI wissen, dass ein Tool fehlgeschlagen ist, damit sie es anders aufrufen oder ein anderes Tool nehmen kann.

In FastMCP ist das einfach: Werfen Sie eine normale Python-Exception, wie oben im Code.

FastMCP wandelt die Exception in eine MCP-Fehlerantwort um und schickt sie an den Client. Der Client entscheidet, was er damit macht, meist gibt er sie an das LLM weiter, das darauf reagiert.

Unterstützte Typen in FastMCP-Tools

Für Eingabeparameter von Tools unterstützt FastMCP die meisten Typen, die auch Pydantic unterstützt: alle eingebauten Typen, Datumswerte, Literals, Enums, Collections (Dicts, Listen), UUIDs, komplexe Pydantic-Modelle und vieles mehr. Die vollständige Liste finden Sie in der Dokumentation von FastMCP.

Bei den Ausgabetypen ist die Auswahl kleiner. Diese Rückgabetypen werden unterstützt:

• str: wird als TextContent gesendet.
• dict, list, Pydantic BaseModel: werden zu einem JSON-String serialisiert und als TextContent gesendet.
• bytes: wird Base64-kodiert und als BlobResourceContents gesendet (oft innerhalb einer EmbeddedResource).
• fastmcp.Image: eine Hilfsklasse, mit der Sie einfach Bilddaten zurückgeben. Wird als ImageContent gesendet.
• None: ergibt eine leere Antwort (der Client bekommt keinen Inhalt zurück).

Fortschrittsmeldungen mit dem FastMCP-Context

Über den Context von FastMCP greifen Sie auf die zugrunde liegende MCP-Session und die Fähigkeiten Ihres MCP-Servers zu, zum Beispiel:

• Logging: Log-Meldungen vom MCP-Server an den Client schicken.
• Zugriff auf Resources: Tools Ihres MCP-Servers brauchen eventuell bereits definierte Resources, etwa um einen Dateipfad aus einer Resource zu holen.
• Fortschrittsmeldungen: Bei lang laufenden Operationen den Fortschritt an den Client melden.

Die fortgeschrittenen Möglichkeiten des Context würden den Rahmen dieses Artikels sprengen. Sie können sie hier nachlesen, und unser Folgebeitrag zu LLM Sampling mit FastMCP (auf Englisch) behandelt eine davon.

In unserem kleinen Projekt bauen wir Fortschrittsmeldungen ein, um zu zeigen, wie der Context funktioniert.

Dafür sind zwei Schritte nötig:

1. Geben Sie der Funktion (Resource oder Tool), in der Sie den Context brauchen, einen Parameter ctx vom Typ Context. Der Name ist egal, der Type Hint Context aber Pflicht.

2. Rufen Sie ctx.report_progress(progress, total) auf, um den Fortschritt an den Client zu melden.

1from typing import Annotated
2
3import aiofiles
4from fastmcp import FastMCP, Context
5from pydantic import Field
6
7mcp = FastMCP(
8    name="Document Assistant",
9    instructions="This server allows to fetch and update documents related to PONDHOUSE DATA DOCS."
10)
11
12@mcp.tool()
13async def edit_file(
14    filename: Annotated[ str, Field( description="Path to the target file", min_length=1, max_length=255) ],
15    ctx: Context,
16    line: Annotated[ str, Field( description="Text content to append to the file", min_length=1) ],
17    second_line: Annotated[ str, Field( description="Optional second line to append to the file", min_length=1), ] = ""
18    ):
19    """
20    Asynchronously appends a line of text to the end of a file.
21    """
22    await ctx.info(f"Appending to {filename}")
23    try:
24        async with aiofiles.open(filename, mode='a') as file:
25            if not line.endswith('\n'):
26                line += '\n'
27            await file.write(line)
28            if second_line:
29                await ctx.report_progress(progress=50, total=100)
30                if not second_line.endswith('\n'):
31                    second_line += '\n'
32                await file.write(second_line)
33
34            await ctx.report_progress(progress=100, total=100)
35    except Exception as e:
36        print(f"Error appending to file: {str(e)}")
37        raise

Das war es schon.

Den MCP-Server testen

Zum Testen starten Sie zuerst den MCP-Server. FastMCP bringt uvicorn bereits mit, Sie führen also einfach Ihre Python-Datei aus. Wenn Sie dieser Anleitung gefolgt sind, nutzt der Server den SSE-Transport und lauscht auf Port 8000.

Danach testen Sie die Funktionen mit einem Tool wie Claude Desktop oder mit einem einfachen eigenen MCP-Client.

1from fastmcp.client import Client
2import asyncio
3
4# Beachten Sie das Pfad-Suffix `sse` bei SSE-Servern
5# Alle Transports: https://gofastmcp.com/clients/client#transports
6sse_url = "http://localhost:8000/sse"
7
8client = Client(sse_url)
9
10
11async def main():
12    # Hier wird die Verbindung aufgebaut
13    async with client:
14        print(f"Client connected: {client.is_connected()}")
15
16        tools = await client.list_tools()
17        print(f"Available tools: {tools}")
18
19        if any(tool.name == "edit_file" for tool in tools):
20            result = await client.call_tool(
21                "edit_file",
22                {
23                    "filename": "hello-world.txt",
24                    "line": "This text will be added to the file.",
25                },
26            )
27            print(f"Greet result: {result}")
28
29    # Hier wird die Verbindung automatisch geschlossen
30    print(f"Client connected: {client.is_connected()}")
31
32
33if __name__ == "__main__":
34    asyncio.run(main())

Eine vollständige Übersicht über die Methoden des FastMCP-Clients finden Sie in der Dokumentation.

Fazit

Wir haben mit FastMCP einen MCP-Server gebaut, der eine Resource, ein Resource Template und ein Tool mit Fortschrittsmeldungen anbietet und über SSE auf Port 8000 läuft. Jeder Client, der MCP implementiert, kann sich jetzt damit verbinden und diese Funktionen nutzen. Wenn Sie bereits eine REST-API haben, müssen Sie nicht jedes Tool von Hand schreiben: Wir zeigen, wie Sie einen MCP-Server automatisch aus OpenAPI und FastAPI erzeugen.

Sie möchten Ihre internen Systeme per MCP-Server für KI-Agenten öffnen, ohne die Kontrolle über Ihre Daten abzugeben? Unser Team für KI-Beratung unterstützt Sie bei Konzept und Umsetzung. Sprechen Sie uns an.

Weiterlesen

• Smolagents: ein minimalistisches Agenten-Framework (auf Englisch): ein schlanker Ansatz für die Agenten-Entwicklung
• Langfuse: LLM Observability mit Open Source: LLM-Anwendungen überwachen und verbessern
• RAG-Qualität mit RAGAS messen: wie Sie Ihre Retrieval-Systeme messen und optimieren
• Zuverlässige KI-Agenten bauen: Best Practices für robuste KI-Agenten
• KI-Agenten mit dem Microsoft Agent Framework: Agenten für Unternehmen, die MCP-Server als Tools nutzen
• LLM-Tools aus jedem Python-SDK (auf Englisch): LangChain-Tools aus einem bestehenden SDK erzeugen, statt sie von Hand zu schreiben
• Text-to-SQL mit NVIDIA Auto Ontology: eine semantische Schicht für Datenbanken, die Agenten über MCP abfragen

Sie möchten zuverlässige KI-Agenten-Systeme bauen?

Wir haben auf Basis aktueller Forschung einen ausführlichen Leitfaden (auf Englisch) erstellt, wie Sie robuste KI-Agenten-Systeme bauen, die auch im produktiven Betrieb funktionieren. Der Leitfaden behandelt:

• die 14 systematischen Fehlerquellen in Multi-Agenten-Systemen
• belegte Best Practices für das Design von Agenten
• strukturierte Kommunikationsprotokolle und Prüfmechanismen

Über den Autor

Andreas Nigg

Mitgründer, Pondhouse Data

Andreas entwickelt seit mehr als acht Jahren Datenanwendungen. Bei Pondhouse Data konzipiert und baut er KI-Systeme und integriert sie in komplexe, gewachsene Unternehmensumgebungen.

Sprechen Sie mit Andreas über Ihr ProjektAuf LinkedIn folgen