Quiz App MCP 服务器

一个使用 FastMCP 构建的 Python MCP（模型上下文协议）服务器。它将工具暴露给：

• 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 之前，先检查数据库连接是否正常：

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

这应该会输出 1。如果它挂起或报错，请先修复 .env/数据库连接——不要试图通过 Claude Desktop 来调试该问题。

本地运行（stdio）

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

或者使用 MCP inspector 手动调用工具（浏览器界面，无需 Claude Desktop——适合单独检查每个工具的请求/响应）。需要 Node/npm，因为它通过 npx 启动：

.\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 工具将我注册为 <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_USER	你的数据库用户
   DB_PASSWORD	你的数据库密码
   DB_NAME	你的数据库名

4. 启动命令：python server.py

5. 在 server.py 中，将 RENDER 分支下的 BASE_URL 更新为你实际的 Render URL。

6. 在 claude.ai → 设置 → 连接器 中添加：https://your-app.onrender.com/mcp

当前 HTTP 端点未配置任何身份验证——任何拥有该 URL 的人都可以调用所有工具，包括基于数据库的工具。这是为了暂时保持设置简单而做出的明确选择；在暴露任何敏感内容之前请重新审视（参见下文“安全”部分）。

注意

目前 OAuth 已从 HTTP 端点移除——我们还没有让 claude.ai 使用此服务器的数据库/工具，因此不值得增加额外的复杂性。如果以后需要，再加回来。

保活

Render 的免费套餐在空闲 15 分钟后会进入休眠状态，这会使休眠后的第一个请求变慢（30–60 秒）或超时。已经采取的缓解措施：

• server.py 中的一个后台线程每 10 分钟 ping 一次 /health。

• 在 https://your-app.onrender.com/health 上添加一个外部监控（例如 UptimeRobot），每 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，也不暴露数据库模式。

• 所有查询都使用参数化 SQL（text("... WHERE id = :id")，而非字符串插值）。

• 任何用户提供的表名/列名在用于 SQL 之前，都应对照允许列表进行检查。

• Render HTTP 端点没有身份验证——请将其视为公开端点。在重新添加身份验证之前，不要添加会暴露敏感数据或执行破坏性数据库操作的工具。

• 任何持有共享 DB_* 凭据的人所访问的都是同一个生产数据库——没有独立的开发/预发布实例。register_user 和 validate_answer 会直接写入该数据库，因此在本地测试时，会在真实测验数据旁边添加真实数据行。测试时请使用有辨识度的 unique_id，并且不要超出必要范围复用这些凭据。