Quiz App MCP server

Ein Python MCP (Model Context Protocol) Server, erstellt mit FastMCP. Stellt Tools bereit für:

• Claude Desktop, lokal, über stdio

• claude.ai, remote, über HTTP (auf Render bereitgestellt)

Optional über SQLAlchemy mit einer MySQL-Datenbank unterstützt.

Projektstruktur

.
├── server.py           # entry point — branches on RENDER env var (stdio vs HTTP)
├── config.py            # loads .env, exposes shared SQLAlchemy engine
├── tools/
│   ├── __init__.py
│   └── quiz.py           # tool definitions — register(mcp) adds them to a FastMCP instance
├── .env                  # secrets — never commit
├── .env.example
└── requirements.txt

Related MCP server: Quiz App MCP server

Einrichtung

git clone https://github.com/sathvik1607/Quiz_mcp_server.git
cd Quiz_mcp_server
python -m venv venv
.\venv\Scripts\pip install -r requirements.txt
copy .env.example .env
# fill in .env with real DB credentials (or remove the DB_* lines if unused)

Prüfe die DB-Verbindung kurz, bevor du sie in Claude Desktop einbindest:

.\venv\Scripts\python.exe -c "from config import engine; from sqlalchemy import text; print(engine.connect().execute(text('SELECT 1')).scalar())"

Das sollte 1 ausgeben. Wenn es hängt oder einen Fehler wirft, behebe zuerst die .env-/DB-Konnektivität – versuche nicht, das über Claude Desktop zu debuggen.

Lokal ausführen (stdio)

.\venv\Scripts\python.exe server.py

Oder verwende den MCP inspector, um Tools manuell aufzurufen (Browser-UI, kein Claude Desktop nötig – gut geeignet, um Request/Response jedes Tools isoliert zu prüfen). Erfordert Node/npm, da er über npx gestartet wird:

.\venv\Scripts\mcp.exe dev server.py

Verwende den Einstiegspunkt mcp.exe in venv\Scripts, nicht python -m mcp – das Paket mcp hat kein __main__, und diese Form schlägt fehl.

Mit Claude Desktop verbinden

Füge es zu %APPDATA%\Claude\claude_desktop_config.json hinzu (führe es mit dem zusammen, was bereits dort steht – überschreibe die Datei nicht):

{
  "mcpServers": {
    "quizapp": {
      "command": "C:\\path\\to\\project\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\project\\server.py"]
    }
  }
}

Verwende absolute Pfade, die zu dem Ort passen, an dem du das Repo geklont hast.

Beende Claude Desktop vollständig und starte es neu – schließe es über das System-Tray, nicht nur das Fenster. Es lädt die MCP-Konfiguration nur bei einem vollständigen Neustart neu.

Überprüfe dann, dass es geladen wurde: Settings → Connectors → quizapp sollte unter „Other tools“ mit 5 Tools aufgeführt sein (Register user, Get question, Validate answer, Generate leaderboard, Review answers).

Das Quiz spielen

Starte einen neuen Chat und sei präzise – eine vage Eingabe wie „let’s start the quiz“ kann zu einem nicht verwandten integrierten Ablauf „generate a quiz“ fehlgeleitet werden, anstatt die Tools dieses Servers aufzurufen. Sage stattdessen zum Beispiel:

„Verwende das Tool register_user, um mich als <name> mit unique_id <id> zu registrieren, und starte dann das Quiz.“

Von dort an steuern die eigenen Anweisungen des Servers (in server.py) den weiteren Ablauf – eine Frage nach der anderen, wobei auf deine Antwort gewartet wird, bevor es weitergeht.

Auf Render bereitstellen (HTTP, für claude.ai)

1. Pushe zu GitHub (.env ist von Git ignoriert – committe es niemals).

2. Erstelle einen Render-Web Service, der mit dem Repo verbunden ist.

3. Setze die Umgebungsvariablen im Render-Dashboard:

   Variable	Wert
   RENDER	true
   DB_HOST	dein DB-Host
   DB_USER	dein DB-Benutzer
   DB_PASSWORD	dein DB-Passwort
   DB_NAME	dein DB-Name

4. Startbefehl: python server.py

5. Aktualisiere in server.py BASE_URL im RENDER-Zweig auf deine tatsächliche Render-URL.

6. Füge unter claude.ai → Settings → Connectors hinzu: https://your-app.onrender.com/mcp

Am HTTP-Endpoint ist derzeit keine Authentifizierung konfiguriert – jeder mit der URL kann jedes Tool aufrufen, auch die datenbankgestützten. Das war eine bewusste Entscheidung, um das Setup vorerst einfach zu halten; überprüfe das erneut, bevor du etwas Sensibles bereitstellst (siehe Sicherheit unten).

Hinweis

OAuth wurde vorerst vom HTTP-Endpoint entfernt – wir setzen claude.ai noch nicht mit der DB/den Tools dieses Servers ein, daher war die zusätzliche Komplexität es nicht wert. Füge es später wieder hinzu, falls nötig.

Keep-alive

Der kostenlose Tarif von Render wechselt nach 15 Minuten Inaktivität in den Schlafmodus, wodurch die erste Anfrage nach dem Aufwachen langsam (30–60s) ist oder eine Zeitüberschreitung auftritt. Bereits umgesetzte Maßnahmen:

• Ein Hintergrundthread in server.py pingt /health alle 10 Minuten.

• Richte einen externen Monitor (z. B. UptimeRobot) für https://your-app.onrender.com/health alle 5 Minuten ein – nicht für /mcp.

Neues Tool hinzufügen

Öffne tools/quiz.py und füge eine Funktion innerhalb von register(mcp) hinzu:

@mcp.tool()
def my_new_tool(param1: str, param2: int) -> dict:
    """
    One-sentence description of what this tool does.
    The agent reads this docstring to decide when to call the tool.

    Args:
        param1: What this string parameter means.
        param2: What this integer parameter means.
    """
    result = do_something(param1, param2)
    return {"result": result}

Kein separater Registrierungsschritt – register(mcp) wird sowohl für die stdio- als auch für die HTTP-Instanz aufgerufen.

Sicherheit

• .env ist von Git ignoriert – committe es niemals.

• Tools geben niemals rohes SQL zurück und legen das DB-Schema nicht offen.

• Alle Abfragen verwenden parametrisiertes SQL (text("... WHERE id = :id"), keine String-Interpolation).

• Jeder vom Benutzer bereitgestellte Tabellen-/Spaltenname sollte vor der Verwendung in SQL gegen eine Allowlist geprüft werden.

• Der Render-HTTP-Endpoint hat keine Authentifizierung – behandle ihn als öffentlich. Füge keine Tools hinzu, die sensible Daten offenlegen oder destruktive DB-Operationen ausführen, bis die Authentifizierung wieder hinzugefügt wurde.

• Jeder, der die gemeinsamen DB_*-Zugangsdaten besitzt, zeigt auf dieselbe Live-Datenbank – es gibt keine separate Dev-/Staging-Instanz. register_user und validate_answer schreiben direkt hinein, sodass lokales Testen echte Zeilen neben echten Quizdaten hinzufügt. Verwende beim Testen eine eindeutige unique_id und verwende diese Zugangsdaten nicht länger als nötig.