QuizHP MCP Server

An interactive quiz MCP server that turns any topic into playable mini-games. Each question renders as a unique canvas game — archery, puzzles, switches, and 125+ more templates.

Features

• 125+ game templates — MCQ and true/false questions each get a unique mini-game (piano keys, treasure chests, archery, bomb defusal, etc.)
• Multi-platform — responsive layouts for desktop and mobile with fullscreen support
• MCP App UI — rich interactive widget rendered inside Claude or ChatGPT
• Three deployment modes — stdio (Claude Desktop), HTTP (remote server), Cloudflare Worker
• Score reporting — quiz results sent back to the AI for follow-up discussion
• No external dependencies — all templates are bundled, no API calls needed

Installation

npm install quizhp

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "quizhp": {
      "command": "npx",
      "args": ["-y", "quizhp"]
    }
  }
}

Claude.ai (Remote HTTP)

Deploy the server and connect via the MCP endpoint:

# Start the HTTP server
npx quizhp start

# Or run directly
node dist/server/index.js

The MCP endpoint is available at http://localhost:3001/mcp.

ChatGPT

Deploy the HTTP server and point ChatGPT's MCP integration to your /mcp endpoint. CORS is pre-configured for chatgpt.com and chat.openai.com.

Cloudflare Worker

# Deploy to Cloudflare Workers
npx wrangler deploy

Usage Examples

Basic Quiz

Ask Claude:

"Quiz me on the solar system"

Claude generates questions and calls the play-quiz tool. Each question appears as a different interactive mini-game.

Document-Based Quiz

"Read this PDF and quiz me on the key concepts"

Claude extracts facts from the document and creates grounded quiz questions.

Custom Configuration

"Give me 15 hard true/false questions about JavaScript closures"

The AI adapts question count, difficulty, and type mix based on your request.

Development

# Install dependencies
npm install

# Build everything (server + view)
npm run build

# Build only the view widget
npm run build:view

# Build only the server
npm run build:server

# Dev mode (auto-reload)
npm run dev

# Start HTTP server
npm start

# Start stdio server
npm run start:stdio

Architecture

src/
  index.ts          — Express HTTP server (Streamable HTTP transport)
  stdio.ts          — Stdio server (Claude Desktop)
  worker.ts         — Cloudflare Worker entry point
  quiz-server.ts    — MCP server factory (tool + resource registration)
  game-store.ts     — In-memory session store with TTL
  template-store.ts — Loads game templates from bundled files
  types.ts          — Shared TypeScript types

view/src/
  QuizApp.tsx       — Main MCP App component
  components/       — React UI (QuizContainer, GameRuntime, EndScreen, etc.)
  store/            — Zustand state management
  hooks/            — postMessage communication hook
  lib/              — Template injection utilities

templates/          — 125+ HTML canvas game templates
  web/mcq/          — Desktop multiple-choice games
  web/true-false/   — Desktop true/false games
  mobile/mcq/       — Mobile multiple-choice games
  mobile/true-false/ — Mobile true/false games

License

MIT