Wie du deinen ersten MCP-Server erstellst: Schritt-für-Schritt-Anleitung

Voraussetzungen

Bevor du beginnst, stelle sicher, dass Folgendes bereit ist:

• Python 3.10 oder höher installiert.
• Grundlegende Vertrautheit mit Python-Funktionen und asynchronem Code.
• uv (schneller Python-Paketmanager) – Installation mit curl -LsSf https://astral.sh/uv/install.sh | sh.
• Ein MCP-Client wie Claude Desktop (von claude.ai/download herunterladen und aktuell halten).
• Ein Texteditor oder eine IDE.

Keine vorherige MCP-Erfahrung ist erforderlich. Wir werden einen praktischen Weather-MCP-Server bauen, der es KI ermöglicht, über die National Weather Service API Echtzeit-Wetterwarnungen und Vorhersagen für die USA abzufragen.

Schritt 1: Umgebung einrichten

Erstelle ein sauberes Projektverzeichnis und initialisiere es mit uv:

mkdir weather-mcp-server
cd weather-mcp-server
uv init
uv venv
source .venv/bin/activate  # Unter Windows: .venv\Scripts\activate
uv add "mcp[cli]" httpx

Dies installiert das offizielle MCP Python SDK (FastMCP) und httpx für API-Aufrufe. Dein Projekt hat jetzt eine pyproject.toml-Datei und eine virtuelle Umgebung.

Erwartete Ausgabe: Ein neuer .venv-Ordner und Abhängigkeiten, die in uv.lock aufgelistet sind.

Schritt grouped 2: Den MCP-Server-Code erstellen

Erstelle die Hauptdatei:

touch weather.py

Füge diesen vollständigen, lauffähigen Code in weather.py ein:

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# MCP-Server initialisieren
mcp = FastMCP("weather")

NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

# Hilfsfunktion für sichere Aufrufe der NWS-API
async def make_nws_request(url: str) -> dict[str, Any] | None:
    headers = {"User-Agent": USER_AGENT, "Accept": "application/geo+json"}
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

# Wetterwarnungen für die KI übersichtlich formatieren
def format_alert(feature: dict) -> str:
    props = feature["properties"]
    return f"""
Event: {props.get("event", "Unknown")}
Area: {props.get("areaDesc", "Unknown")}
Severity: {props.get("severity", "Unknown")}
Description: {props.get("description", "No description available")}
Instructions: {props.get("instruction", "No specific instructions provided")}
"""

# Tool 1: Aktive Wetterwarnungen für einen US-Bundesstaat abrufen
@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get current weather alerts for a U.S. state (e.g., "CA" or "TX")."""
    url = f"{NWS_API_BASE}/alerts/active/area/{state.upper()}"
    data = await make_nws_request(url)
    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."
    if not data["features"]:
        return f"No active alerts for {state.upper()}."
    alerts = [format_alert(f) for f in data["features"]]
    return "\n---\n".join(alerts)

# Tool 2: Hole 5-Tage-Vorhersage für beliebige Lat/Long-Koordinaten
@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Hole Wettervorhersage für einen spezifischen Breiten- und Längengrad."""
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)
    if not points_data:
        return "Kann keine Vorhersagedaten für diesen Standort abrufen."
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)
    if not forecast_data:
        return "Kann keine detaillierte Vorhersage abrufen."
    periods = forecast_data["properties"]["periods"][:5]
    forecasts = []
    for period in periods:
        forecast = f"""
{period["name"]}:
Temperatur: {period["temperature"]}°{period["temperatureUnit"]}
Wind: {period["windSpeed"]} {period["windDirection"]}
Vorhersage: {period["detailedForecast"]}
"""
        forecasts.append(forecast)
    return "\n---\n".join(forecasts)

def main():
    mcp.run(transport="stdio")

if __name__ == "__main__":
    main()

Erklärte Schlüsselkonzepte:

• @mcp.tool()-Dekoratoren verwandeln reguläre asynchrone Funktionen in MCP-Tools, die KI entdecken und aufrufen kann.
• Der Server läuft über stdio (Standard-Eingabe/Ausgabe) – die Standardmethode für lokale MCP-Server.
• Alle Logs sollten an stderr gehen (FastMCP erledigt dies automatisch).

Schritt 3: Testen Sie den Server lokal

Starten Sie den Server:

uv run weather.py

Erwartete Ausgabe: Das Terminal bleibt offen und stumm (das ist normal für stdio-Server). Sie werden nur JSON-RPC-Nachrichten sehen, wenn sich ein MCP-Client verbindet.

Lassen Sie dieses Terminal für den nächsten Schritt laufen.

Schritt 4: Verbinden Sie den MCP-Server mit Claude Desktop

1. Öffnen Sie Claude Desktop.
2. Erstellen oder bearbeiten Sie die Konfigurationsdatei unter:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

Fügen Sie diesen exakten Eintrag hinzu (ersetzen Sie /ABSOLUTE/PATH/TO/weather-mcp-server mit Ihrem tatsächlichen Ordnerpfad):

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/weather-mcp-server",
        "run",
        "weather.py"
      ]
    }
  }
}

3. Beenden Sie Claude Desktop vollständig (Cmd+Q auf macOS oder über System-Tray auf Windows) und starten Sie es neu.
4. In Claude klicken Sie auf „Dateien, Konnektoren und mehr hinzufügen“ → fahren Sie mit der Maus über Konnektoren → Sie sollten „weather“ aufgelistet sehen.

Schritt 5: Verwenden Sie Ihren MCP-Server mit KI

Probieren Sie diese Prompts in Claude Desktop aus:

• „Welche aktiven Wetterwarnungen gibt es in Texas?“
• „Gib mir die Vorhersage für San Francisco (verwende lat 37.77, long -122.41).“
• „Prüfe Warnungen in Kalifornien und sag mir, ob ich mich auf irgendetwas vorbereiten muss.“

Claude wird die Tools automatisch entdecken, beim ersten Mal Ihre Zustimmung einholen und formatierte Ergebnisse zurückgeben.

Erwartetes Verhalten: Die KI ruft Ihre Tools im Hintergrund auf und zeigt Antworten in natürlicher Sprache an.

Häufige Probleme und Fehlerbehebung

• Server erscheint nicht in Claude:

  • JSON-Datei auf Gültigkeit prüfen (keine abschließenden Kommas).
  • Absoluten Pfad in der Konfiguration verwenden.
  • Claude-Anwendung vollständig neu starten.
  • Logs überprüfen: ~/Library/Logs/Claude/mcp*.log (macOS) oder entsprechendes auf Windows.

• API-Fehler oder keine Daten:

  • NWS-API funktioniert nur für Standorte in den USA.
  • Zwei-Buchstaben-Bundesstaats-Codes verwenden (CA, TX, etc.).
  • Koordinaten müssen gültige Längen-/Breitengrade sein.

.

.

• "Befehl nicht gefunden":
  • Sicherstellen, dass uv im PATH enthalten und die virtuelle Umgebung aktiviert ist.
  • uv --version ausführen, um die Installation zu überprüfen.

7

• Timeout oder langsame Antwort:

  • Timeout in make_nws_request bei Bedarf erhöhen.
  • NWS hat Ratenbegrenzungen – Spamming in Produktionsumgebungen vermeiden.

• Berechtigungsprobleme:

  • Unter macOS: Claude Desktop in Systemeinstellungen → Privatsphäre & Sicherheit den vollständigen Festplattenzugriff gewähren.

Nächste Schritte

• Weitere Tools hinzufügen: Tools für Datenbanken, GitHub, Slack oder eigene APIs mithilfe des gleichen @mcp.tool()-Schemas erstellen.
• Ressourcen und Prompts hinzufügen: mcp.resource() und mcp.prompt() für dateiähnliche Daten und wiederverwendbare Anweisungen nutzen. . - Remote-Bereitstellung: Zu HTTP/SSE-Transport wechseln und auf AWS Lambda, Vercel oder einem beliebigen Server hosten (FastMCP unterstützt stateless_http=True).
• Mehrsprachigkeit unterstützen: Offizielle TypeScript-, Go- oder Rust-SDKs für die gleiche Funktionalität ausprobieren.
• Server teilen: Repository veröffentlichen, damit andere es via npx oder Docker hinzufügen können.

Sie haben jetzt einen voll funktionsfähigen MCP-Server, den jeder kompatible KI-Client nutzen kann. Experimentieren Sie, erweitern Sie die Tools und beginnen Sie noch heute, leistungsstarke KI-Integrationen zu entwickeln!