MCP-Server in Python entwickeln: Vom leeren Repo zum ersten Tool

Warum ein eigener MCP-Server?

Setup

pip install fastmcp
# oder mit uv (empfohlen)
uv add fastmcp

uv add fastmcp httpx

Stufe 1: stdio-Transport (Claude Code lokal)

Hello World

# server.py
from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def hello(name: str) -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()

Integration in Claude Code

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/absoluter/pfad/zu/server.py"]
    }
  }
}

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": ["run", "/absoluter/pfad/zu/server.py"]
    }
  }
}

Echtes Tool mit Parameter-Validierung

from fastmcp import FastMCP
from pydantic import Field
from typing import Optional
import httpx

mcp = FastMCP("devmaker")

@mcp.tool()
async def get_articles(
    limit: int = Field(default=10, ge=1, le=100, description="Anzahl Artikel"),
    topic: Optional[str] = Field(default=None, description="Topic-Slug, z.B. 'linux'")
) -> str:
    """Artikel aus dem CMS abrufen. Gibt Titel, ID und URL zurück."""
    params = {"limit": limit}
    if topic:
        params["topic"] = topic
    async with httpx.AsyncClient() as client:
        resp = await client.get("http://localhost:8000/api/articles/", params=params)
        resp.raise_for_status()
        data = resp.json()
    lines = [f"- [{a['title']}]({a['url']}) (ID {a['id']})" for a in data["results"]]
    return "\n".join(lines) or "Keine Artikel gefunden."

Fehlerbehandlung

@mcp.tool()
async def publish_article(page_id: int) -> str:
    """Artikel veröffentlichen. Gibt URL zurück oder Fehlermeldung."""
    try:
        async with httpx.AsyncClient() as client:
            resp = await client.post(f"http://localhost:8000/api/pages/{page_id}/publish/")
            resp.raise_for_status()
            return f"Veröffentlicht: {resp.json()['url']}"
    except httpx.HTTPStatusError as e:
        return f"Fehler {e.response.status_code}: {e.response.text}"

Stufe 2: HTTP/SSE-Transport (Remote, Production)

Wann HTTP/SSE?

Server auf HTTP/SSE umstellen

# server.py
from fastmcp import FastMCP
import uvicorn

mcp = FastMCP("devmaker", stateless_http=True)

# ... Tool-Definitionen wie bisher ...

if __name__ == "__main__":
    uvicorn.run(mcp.http_app(), host="0.0.0.0", port=8080)

Docker Compose

services:
  mcp-server:
    build: .
    ports:
      - "8080:8080"
    environment:
      - API_BASE_URL=${API_BASE_URL}
      - API_TOKEN=${API_TOKEN}
    restart: unless-stopped

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY server.py .
CMD ["python", "server.py"]

Claude Code mit Remote-Server

{
  "mcpServers": {
    "devmaker-remote": {
      "type": "http",
      "url": "http://mein-server.intern:8080/mcp"
    }
  }
}

{
  "mcpServers": {
    "devmaker-remote": {
      "type": "http",
      "url": "https://mcp.devmaker.net/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

Ressourcen (Resources)

import json

@mcp.resource("config://server-info")
def server_info() -> str:
    """Gibt Server-Konfiguration und verfügbare Topics zurück."""
    return json.dumps({
        "version": "1.0",
        "topics": ["linux", "homelab", "home-automation", "elektronik", "3d-druck"],
        "max_articles_per_request": 50
    }, ensure_ascii=False)

Auth: Bearer Token

from fastmcp import FastMCP
from fastmcp.server.auth import BearerAuthProvider
import os

mcp = FastMCP("devmaker", stateless_http=True)

# FastMCP >= 2.x: auth via server-Parameter
mcp_with_auth = FastMCP(
    "devmaker",
    stateless_http=True,
    auth=BearerAuthProvider(token=os.environ["MCP_TOKEN"])
)

Lessons Learned

if __name__ == "__main__":
    import sys
    if "--http" in sys.argv:
        import uvicorn
        uvicorn.run(mcp.http_app(), host="0.0.0.0", port=8080)
    else:
        mcp.run()  # stdio

Fazit