Quiz App MCP server

Un servidor MCP (Model Context Protocol) de Python construido con FastMCP. Expone herramientas para:

• Claude Desktop, localmente, a través de stdio

• claude.ai, de forma remota, a través de HTTP (desplegado en Render)

Opcionalmente, respaldado por una base de datos MySQL mediante SQLAlchemy.

Estructura del proyecto

.
├── 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: leafeep-mcp

Configuración

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)

Verifica la conexión a la base de datos antes de integrarlo en Claude Desktop:

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

Esto debería imprimir 1. Si se cuelga o da error, arregla primero la conectividad de .env/DB — no intentes depurar eso a través de Claude Desktop.

Ejecutar localmente (stdio)

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

O usa el inspector MCP para llamar a las herramientas manualmente (interfaz de navegador, no se necesita Claude Desktop — útil para comprobar la petición/respuesta de cada herramienta de forma aislada). Requiere Node/npm, ya que se lanza mediante npx:

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

Usa el punto de entrada mcp.exe en venv\Scripts, no python -m mcp — el paquete mcp no tiene __main__ y esa forma falla.

Conectar con Claude Desktop

Añádelo a %APPDATA%\Claude\claude_desktop_config.json (combínalo con lo que ya haya — no sobrescribas el archivo):

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

Usa rutas absolutas que coincidan con el lugar donde clonaste el repositorio.

Cierra y reinicia Claude Desktop por completo — ciérralo desde la bandeja del sistema, no solo la ventana. Solo recarga la configuración de MCP en un reinicio completo.

Luego verifica que se cargó: Settings → Connectors → quizapp debería aparecer en "Other tools" con 5 herramientas (Register user, Get question, Validate answer, Generate leaderboard, Review answers).

Jugar al quiz

Inicia un nuevo chat y sé explícito: un prompt vago como "empecemos el quiz" puede desviarse a un flujo integrado no relacionado de "generar un quiz" en lugar de llamar a las herramientas de este servidor. En su lugar, di algo como:

"Usa la herramienta register_user para registrarme como <name> con unique_id <id>, y luego empieza el quiz."

A partir de ahí, las propias instrucciones del servidor (en server.py) guían el resto del flujo: una pregunta cada vez, esperando tu respuesta antes de continuar.

Desplegar en Render (HTTP, para claude.ai)

1. Haz push a GitHub (.env está en gitignore — nunca lo incluyas en un commit).

2. Crea un Web Service de Render conectado al repositorio.

3. Configura las variables de entorno en el panel de Render:

   Variable	Valor
   RENDER	true
   DB_HOST	el host de tu base de datos
   DB_USER	el usuario de tu base de datos
   DB_PASSWORD	la contraseña de tu base de datos
   DB_NAME	el nombre de tu base de datos

4. Comando de inicio: python server.py

5. En server.py, actualiza BASE_URL en la rama RENDER con tu URL real de Render.

6. En claude.ai → Settings → Connectors, añade: https://your-app.onrender.com/mcp

Actualmente no hay autenticación configurada en el endpoint HTTP — cualquiera con la URL puede llamar a todas las herramientas, incluidas las que usan la base de datos. Esta fue una decisión explícita para mantener la configuración sencilla por ahora; revísala antes de exponer algo sensible (ver Seguridad más abajo).

Nota

Se eliminó OAuth del endpoint HTTP por ahora — todavía no estamos usando claude.ai para acceder a la base de datos/las herramientas de este servidor, por lo que no valía la pena la complejidad adicional. Vuelve a añadirlo más adelante si es necesario.

Keep-alive

El plan gratuito de Render se duerme después de 15 minutos de inactividad, lo que hace que la primera solicitud tras el reposo sea lenta (30–60s) o expire. Mitigaciones ya implementadas:

• Un hilo en segundo plano en server.py hace ping a /health cada 10 minutos.

• Añade un monitor externo (por ejemplo, UptimeRobot) en https://your-app.onrender.com/health cada 5 minutos — no en /mcp.

Añadir una nueva herramienta

Abre tools/quiz.py y añade una función dentro de register(mcp):

@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}

No hay ningún paso de registro aparte — se llama a register(mcp) tanto para las instancias de stdio como para las de HTTP.

Seguridad

• .env está en gitignore — nunca lo incluyas en un commit.

• Las herramientas nunca devuelven SQL crudo ni exponen el esquema de la base de datos.

• Todas las consultas usan SQL parametrizado (text("... WHERE id = :id"), no interpolación de cadenas).

• Cualquier nombre de tabla/columna proporcionado por el usuario debe comprobarse contra una lista blanca antes de usarse en SQL.

• El endpoint HTTP de Render no tiene autenticación — trátalo como público. No añadas herramientas que expongan datos sensibles u operaciones destructivas sobre la base de datos hasta que se vuelva a añadir la autenticación.

• Quien tenga las credenciales compartidas DB_* tiene acceso a la misma base de datos real — no hay una instancia separada de desarrollo/staging. register_user y validate_answer escriben directamente en ella, por lo que probar localmente añade filas reales junto a los datos reales del quiz. Usa un unique_id distintivo al probar y no reutilices estas credenciales más de lo necesario.