Quiz App MCP server

FastMCP で構築された Python MCP (Model Context Protocol) サーバー。以下のツールを公開します:

• ローカルでは stdio 経由で Claude Desktop に

• リモートでは HTTP 経由で claude.ai に (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 設定は完全な再起動でのみ再読み込みされます。

次に、読み込まれたことを確認します: 設定 → コネクタ → quizapp が「その他のツール」の下に 5 つのツール (Register user, Get question, Validate answer, Generate leaderboard, Review answers) とともに表示されているはずです。

クイズをプレイする

新しいチャットを開始し、明確に指示してください — 「クイズを始めましょう」のような曖昧なプロンプトは、このサーバーのツールを呼び出す代わりに、無関係な組み込みの「クイズを生成」フローに誤ってルーティングされる可能性があります。代わりに、次のように言ってください:

"register_user ツールを使用して、unique_id <id> で <name> として登録し、クイズを 開始してください。"

そこから先は、サーバー自身の指示 (server.py 内) がフローの残りを進めます — 一度に 1 問ずつ、あなたの回答を待ってから次に進みます。

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 → 設定 → コネクタ で、https://your-app.onrender.com/mcp を追加する。

現在、HTTP エンドポイントには認証が設定されていません — URL を知っている人は誰でも、DB を使用するものを含むすべてのツールを呼び出すことができます。これは当面のセットアップを簡単にするための意図的な選択であり、機密情報を公開する前に見直してください (下記の「セキュリティ」を参照)。

注記

OAuth は現在、HTTP エンドポイントから削除されています — このサーバーの DB/ツールに対して claude.ai をまだ使用していないため、余分な複雑さを加える価値がありませんでした。必要になれば後で追加し直してください。

キープアライブ

Render の無料プランは 15 分間アイドル状態が続くとスリープするため、スリープ後の最初のリクエストは遅くなるか (30–60秒)、タイムアウトします。すでに講じている対策:

• server.py 内のバックグラウンドスレッドが /health に 10 分ごとに ping を送信します。

• https://your-app.onrender.com/health に 5 分ごとに外部モニター (例: UptimeRobot) を設定してください — /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 を使用し、必要以上にこれらの認証情報を使い回さないでください。