Quiz App MCP 서버

FastMCP로 구축된 Python MCP(Model Context Protocol) 서버입니다. 다음에 도구를 제공합니다:

• Claude Desktop, 로컬에서, stdio를 통해

• claude.ai, 원격에서, HTTP를 통해 (Render에 배포)

선택적으로 SQLAlchemy를 통해 MySQL 데이터베이스를 사용할 수 있습니다.

프로젝트 구조

.
├── 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

설정

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)

Claude Desktop에 연결하기 전에 DB 연결을 사전 점검하세요:

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

1이 출력되어야 합니다. 멈추거나 오류가 발생하면 먼저 .env/DB 연결을 수정하세요 — Claude Desktop을 통해 디버그하려고 하지 마세요.

로컬 실행 (stdio)

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

또는 MCP inspector를 사용하여 도구를 수동으로 호출할 수 있습니다(브라우저 UI이며 Claude Desktop이 필요 없음 — 각 도구의 요청/응답을 개별적으로 확인하기에 좋습니다). npx를 통해 실행되므로 Node/npm이 필요합니다:

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

venv\Scripts의 mcp.exe 진입점을 사용하고 python -m mcp는 사용하지 마세요 — mcp 패키지에는 __main__이 없어 해당 형식은 실패합니다.

Claude Desktop에 연결

%APPDATA%\Claude\claude_desktop_config.json에 추가하세요(이미 있는 내용에 병합 — 파일을 덮어쓰지 마세요):

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

리포지토리를 클론한 위치에 맞는 절대 경로를 사용하세요.

Claude Desktop을 완전히 종료하고 다시 시작하세요 — 창을 닫는 것만으로는 부족하며 시스템 트레이에서 종료해야 합니다. 전체 재시작 시에만 MCP 구성을 다시 로드합니다.

그런 다음 로드되었는지 확인하세요: Settings → Connectors → quizapp이 "Other tools" 아래에 5개의 도구(Register user, Get question, Validate answer, Generate leaderboard, Review answers)와 함께 표시되어야 합니다.

퀴즈 플레이

새 채팅을 시작하고 명시적으로 말하세요 — "퀴즈 시작하자" 같은 모호한 프롬프트는 이 서버의 도구를 호출하는 대신 관련 없는 내장 "퀴즈 생성" 흐름으로 잘못 라우팅될 수 있습니다. 대신 다음과 같이 말하세요:

"register_user 도구를 사용하여 저를 <name>(으)로, unique_id <id>(으)로 등록한 다음 퀴즈를 시작하세요."

그다음부터는 서버 자체 지침(server.py에 있음)이 나머지 흐름을 주도합니다 — 한 번에 한 문제씩, 답변을 기다린 후 다음으로 넘어갑니다.

Render에 배포 (HTTP, claude.ai용)

1. GitHub에 푸시하세요 (.env는 gitignore 처리되어 있습니다 — 절대 커밋하지 마세요).

2. 리포지토리에 연결된 Render Web Service를 생성하세요.

3. Render 대시보드에서 환경 변수를 설정하세요:

   변수	값
   RENDER	true
   DB_HOST	DB 호스트
   DB_USER	DB 사용자
   DB_PASSWORD	DB 비밀번호
   DB_NAME	DB 이름

4. 시작 명령: python server.py

5. server.py의 RENDER 분기에서 BASE_URL을 실제 Render URL로 업데이트하세요.

6. claude.ai → Settings → Connectors에서 https://your-app.onrender.com/mcp를 추가하세요.

현재 HTTP 엔드포인트에는 인증이 구성되어 있지 않습니다 — URL을 가진 사람은 누구나 DB 기반 도구를 포함한 모든 도구를 호출할 수 있습니다. 이는 현재 설정을 단순하게 유지하기 위한 명시적인 선택이었습니다. 민감한 정보를 노출하기 전에 다시 검토하세요(아래 보안 참조).

참고

OAuth는 현재 HTTP 엔드포인트에서 제거되었습니다 — 아직 claude.ai에서 이 서버의 DB/도구를 사용하지 않으므로 추가 복잡성을 감수할 가치가 없었습니다. 필요하면 나중에 다시 추가하세요.

Keep-alive

Render의 무료 티어는 15분 동안 유휴 상태이면 절전 모드로 전환되어, 절전 후 첫 요청이 느려지거나(30–60초) 시간 초과될 수 있습니다. 이미 적용된 완화 조치는 다음과 같습니다:

• server.py의 백그라운드 스레드가 10분마다 /health에 ping을 보냅니다.

• 외부 모니터(예: UptimeRobot)로 https://your-app.onrender.com/health를 5분마다 모니터링하세요 — /mcp가 아닙니다.

새 도구 추가

tools/quiz.py를 열고 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}

별도의 등록 단계는 없습니다 — register(mcp)는 stdio 및 HTTP 인스턴스 모두에서 호출됩니다.

보안

• .env는 gitignore 처리되어 있습니다 — 절대 커밋하지 마세요.

• 도구는 원시 SQL을 반환하거나 DB 스키마를 노출하지 않습니다.

• 모든 쿼리는 매개변수화된 SQL을 사용합니다 (text("... WHERE id = :id"), 문자열 보간이 아님).

• 사용자가 제공한 테이블/열 이름은 SQL에서 사용하기 전에 허용 목록과 대조하여 확인해야 합니다.

• Render HTTP 엔드포인트에는 인증이 없습니다 — 공개된 것으로 취급하세요. 인증이 다시 추가될 때까지 민감한 데이터를 노출하거나 파괴적인 DB 작업을 수행하는 도구를 추가하지 마세요.

• 공유 DB_* 자격 증명을 가진 사람은 누구나 동일한 라이브 데이터베이스를 가리킵니다 — 별도의 dev/staging 인스턴스는 없습니다. register_user와 validate_answer는 데이터베이스에 직접 쓰므로 로컬에서 테스트하면 실제 퀴즈 데이터 옆에 실제 행이 추가됩니다. 테스트할 때는 고유한 unique_id를 사용하고, 필요한 범위를 넘어 이러한 자격 증명을 재사용하지 마세요.