Konfigurieren eines lokalen MCP-Servers (STDIO)
Auf dieser Seite
Aktualisiert am 2. November 2026 — MCP Python SDK v2. Dieser Kurs folgt nun Version 2 des
mcpSDKs (Stand 2.3.0 vom 2. Oktober 2026):MCPServerersetztFastMCP, Transport-Einstellungen werden inrun()oderstreamable_http_app()verlegt, und eine Anwendung, die unter einem echten Hostnamen bereitgestellt wird, muss diesen Hostnamen deklarieren (transport_security). Dies ist auch die vom Mistral SDK erforderliche Version: Dasmistralai[agents]-Extra benötigtmcp>=2.2.0,<3.0. Quellen: Was ist neu in v2 · Migrationsanleitung · Bereitstellen & Skalieren.
Ihr erster lokaler MCP-Server
Der STDIO-Modus ist der natürliche Ausgangspunkt für die Entwicklung und das Testen eines MCP-Servers: Alles läuft auf Ihrem Gerät, ohne Bereitstellung, ohne öffentliche URL und ohne zu verwaltende Zertifikate. Sie bearbeiten eine Datei, starten neu und beobachten das Ergebnis. In dieser Lektion schreiben Sie einen lokalen MCP-Server in Python und verbinden ihn anschließend mit einem Client.
Als Voraussetzungen benötigen Sie Python 3.10 oder höher, einen aktuellen pip und vorzugsweise eine dedizierte virtuelle Umgebung. Der letzte Punkt ist nicht kosmetischer Natur: MCP-Pakete entwickeln sich schnell weiter, und eine separate venv pro Projekt verhindert, dass Sie einen funktionierenden Server zerstören, wenn Sie eine Abhängigkeit für ein anderes Projekt installieren.
# Virtuelle Umgebung erstellen
python -m venv mcp-env
source mcp-env/bin/activate # Linux/Mac
# mcp-env\Scripts\activate # Windows
# Offizielles MCP SDK (v2) und Mistral SDK mit dem agents-Extra
pip install "mcp[cli]>=2.2,<3" "mistralai[agents]"
Den Server schreiben
Mit MCPServer, der High-Level-Klasse im offiziellen SDK (ehemals FastMCP), benötigt ein lokaler Server nur wenige Zeilen. Sie instanzenzieren eine Anwendung, indem Sie ihr einen beschreibenden Namen geben, und dekorieren Ihre Python-Funktionen mit @app.tool(), um sie zu exponieren.
# serveur_local.py
from mcp.server.mcpserver import MCPServer
# Initialisieren des Servers mit einem beschreibenden Namen
app = MCPServer("Local Demo Server")
@app.tool()
def greet(name: str) -> str:
"""Begrüßt eine Person nach Namen.
Args:
name: Der Vorname der zu begrüßenden Person
Returns:
Eine personalisierte Begrüßungsnachricht
"""
return f"Hello {name}! Welcome to the world of MCP."
@app.tool()
def calculate(operation: str, a: float, b: float) -> str:
"""Führt eine einfache mathematische Berechnung durch.
Args:
operation: Die durchzuführende Operation (add, sub, mul, div)
a: Erste Zahl
b: Zweite Zahl
Returns:
Das Ergebnis der Berechnung
"""
ops = {
"add": a + b,
"sub": a - b,
"mul": a * b,
"div": a / b if b != 0 else "Error: division by zero"
}
result = ops.get(operation, "Unknown operation")
return f"{a} {operation} {b} = {result}"
Diese Datei exponiert zwei Tools. Beachten Sie die Rolle der Docstrings: Sie dokumentieren Ihren Code nicht nur für einen Kollegen, sie werden wörtlich zur Beschreibung, die das Modell liest, um zu entscheiden, ob es calculate statt greet aufrufen soll. Ein schlampiger Docstring führt hier später zu unregelmäßigen Aufrufen.
Konfigurieren des STDIO-Clients
Auf der Client-Seite verbinden Sie sich nicht mit einer Adresse; Sie erklären, wie der Server gestartet wird. Das ist die Aufgabe von StdioServerParameters.
# client_stdio.py
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from pathlib import Path
# Pfad zu Ihrem Server
path_to_server = Path("serveur_local.py")
# STDIO-Server-Konfiguration
server_params = StdioServerParameters(
command="python", # Der Befehl zum Starten des Servers
args=[str(path_to_server)], # Die Argumente (die Python-Datei)
env=None, # Umgebungsvariablen (optional)
)
# Erstellen des MCP-Clients
mcp_client = MCPClientSTDIO(stdio_params=server_params)
Drei Parameter verdienen eine nähere Betrachtung.
command
Dies ist der Systembefehl, der den Server-Prozess startet: "python" für einen Python-Server, "node" für einen JavaScript-Server oder der direkte Pfad zu einem Binary, wenn Ihr Server kompiliert ist.
# Python
command="python"
# Node.js
command="node"
# Ein kompiliertes Executable
command="./mon_serveur_mcp"
args
Dies ist die Liste der Argumente, die an diesen Befehl übergeben werden. Bei einer Python-Skript ist dies mindestens der Dateipfad, aber es schadet nichts, wenn Sie hier die Optionen Ihres Servers übergeben.
# Einfaches Skript
args=["serveur_local.py"]
# Mit zusätzlichen Argumenten
args=["serveur_local.py", "--port", "8080", "--verbose"]
env
Dies ist das Wörterbuch der Umgebungsvariablen, die an den Server-Prozess übergeben werden: der Kanal, über den Sie ihm einen API-Schlüssel, eine Datenbank-URL oder ein Debug-Flag übergeben.
import os
server_params = StdioServerParameters(
command="python",
args=["serveur_local.py"],
env={
**os.environ, # Vererbung von der aktuellen Umgebung
"API_KEY": "your_api_key",
"DATABASE_URL": "postgresql://...",
"DEBUG": "true",
},
)
Das Verhalten dieses Parameters überrascht Menschen oft. Bei env=None erbt der Server die gesamte Umgebung des Elternprozesses; bei einem Wörterbuch sieht er streng nur die aufgeführten Variablen. Wenn Sie ein Wörterbuch bereitstellen, ohne os.environ hineinzudümpfen, wundern Sie sich nicht, wenn Ihr Server seine PATH-Variable oder seinen API-Schlüssel nicht mehr findet: Das Verhalten ist vollkommen logisch, nur radikal.
Testen vor der Integration
Bevor Sie Ihren Server in einen Agenten einbinden, testen Sie ihn isoliert mit dem MCP Inspector. Die Begründung ist einfach: Wenn ein Aufruf fehlschlägt, sobald der Server mit einem Modell verbunden ist, wissen Sie nicht, ob das Problem in Ihrem Code oder in der Entscheidung des Modells liegt. Der Inspector beseitigt diese Mehrdeutigkeit.
npx @modelcontextprotocol/inspector python serveur_local.py
Der Befehl öffnet eine lokale Web-Oberfläche, in der Sie die exponierten Tools auflisten, die Beschreibung und Parameter prüfen können, die das Modell erhält, einen manuellen Aufruf mit beliebigen Argumenten auslösen und das genaue Format des Rückgabewerts verifizieren können. Machen Sie es zur Gewohnheit, dies systematisch einzusetzen: Es sind fünf Minuten, die eine Stunde sparen.
Abschließend hier eine Dateistruktur, die sich bewährt, mit Server, Client, Abhängigkeiten, Geheimnissen, die aus dem Repository entfernt sind, und Unit-Tests für Ihre Tools:
mon-projet-mcp/
├── serveur_local.py # Der MCP-Server
├── client_stdio.py # Das Client-Skript
├── requirements.txt # Abhängigkeiten
├── .env # Umgebungsvariablen (niemals committen)
└── tests/
└── test_tools.py # Unit-Tests für Tools
Kernaussagen
- Ein STDIO-Server startet als lokaler Prozess
StdioServerParameterskonfiguriert den Befehl, die Argumente und die Umgebungsvariablen- Die Docstrings Ihrer Tools dienen als Beschreibung für das Modell
- Der MCP Inspector (
npx @modelcontextprotocol/inspector) ist unerlässlich für Tests env=Noneerbt die gesamte Umgebung; ein explizites Wörterbuch limitiert die Variablen