Quiz MCP
MCP server for interactive quizzes
Quiz MCP
A Model Context Protocol (MCP) server for running interactive quizzes. This tool bridges the gap between AI generation and user interaction by allowing agents to generate quizzes and immediately present them to users in a polished web interface.
Features
- Interactive Web UI: Built with SvelteKit 5 + Tailwind CSS + DaisyUI for a responsive and smooth experience.
- MCP Support: Fully compatible with Model Context Protocol for AI agent integration.
- 8 Question Types:
- Single Choice - Radio button selection
- Multiple Choice - Checkbox selection
- Remove Extra - Identify and select incorrect items
- Order - Drag-and-drop reordering
- Match - Click-to-match pairs
- Text - Free-form textarea input
- Input - Single-line text input
- Input List - Dynamic list of text inputs
- Flexible Configuration: Theme, timer, shuffling, progress indicators, and more.
- CLI Tool: Easy-to-use command line interface for local testing and usage.
- i18n Ready: Built-in internationalization support (English, Spanish, Russian, Ukrainian).
- Storybook: Component documentation and development.
Local-first & Privacy by Design
Quiz MCP runs entirely on your machine.
- No external APIs
- No cloud services
- No telemetry
- No user data leaves your system
AI agents communicate with the quiz UI through a local MCP server. All interactions stay within your local environment (unless you explicitly configure a webhook).
Installation
pnpm install
pnpm build
Usage
CLI Commands
Quiz MCP provides two CLI commands:
quiz run
Run interactive quizzes via CLI with browser interface.
Usage:
node bin/quiz-mcp run [options]
Options:
| Option | Description |
|---|---|
-f, --file <PATH> | Path to quiz JSON file |
-q, --quiz <JSON> | Direct JSON quiz data |
-u, --url <URL> | URL to fetch quiz JSON from |
-c, --config <PATH> | Path to configuration file |
-o, --output <PATH> | Output results file path |
-w, --webhook-url <URL> | Webhook URL for results |
-p, --port <NUMBER> | Server port (default: 3000) |
-h, --host <STRING> | Server host (default: localhost) |
--auto-port | Automatically use a free port if the requested port is in use |
-O, --open | Auto-open browser |
-v, --verbose | Verbose logging |
Examples:
# Run a quiz from a file
node bin/quiz-mcp run --file ./my-quiz.json
# Run with auto-open browser
node bin/quiz-mcp run --file ./quiz.json --open
# Run and save results to file
node bin/quiz-mcp run --file ./quiz.json --output ./results.json
# Run on custom port
node bin/quiz-mcp run --file ./quiz.json --port 8080
# Run with inline JSON
node bin/quiz-mcp run --quiz '{"title":"Test","questions":[{"id":"q1","type":"single","question":"Test?","options":["A","B"]}]}'
# Run a quiz from a URL
node bin/quiz-mcp run --url "https://raw.githubusercontent.com/karerckor/quiz-mcp/main/quiz-examples/javascript-fundamentals.jsonc"
Try Example Quizzes
You can run the example quizzes directly from the GitHub repository without cloning:
# Run JavaScript Fundamentals quiz (via npx)
npx quiz-mcp run --url "https://raw.githubusercontent.com/karerckor/quiz-mcp/main/quiz-examples/javascript-fundamentals.jsonc"
# Run Web Development quiz (via pnpx)
pnpx quiz-mcp run --url "https://raw.githubusercontent.com/karerckor/quiz-mcp/main/quiz-examples/web-development.jsonc"
# Run with auto-open browser
npx quiz-mcp run --url "https://raw.githubusercontent.com/karerckor/quiz-mcp/main/quiz-examples/javascript-fundamentals.jsonc" --open
quiz mcp
Run as MCP server for AI agent integration.
Usage:
node bin/quiz-mcp mcp [options]
Options:
| Option | Description |
|---|---|
-c, --config <PATH> | MCP configuration file path |
--quiz-config <PATH> | Quiz configuration file path (layout, theme, language, webhook) |
-s, --storage <PATH> | Session storage directory |
-m, --max-sessions <NUMBER> | Maximum concurrent sessions |
-q, --quiz <PATH> | Default quiz file path |
-l, --log-level <LEVEL> | Log level (debug, info, warn, error) |
-p, --port <NUMBER> | Server port (default: 3000) |
-h, --host <STRING> | Server host (default: localhost) |
--auto-port | Automatically use a free port if the requested port is in use |
-v, --verbose | Verbose logging |
Examples:
# Start MCP server with default settings
node bin/quiz-mcp mcp
# Start on custom port
node bin/quiz-mcp mcp --port 8080
# With custom quiz configuration
node bin/quiz-mcp mcp --quiz-config ./quiz-config.json
# With custom session storage
node bin/quiz-mcp mcp --storage ./sessions --max-sessions 50
# With verbose logging
node bin/quiz-mcp mcp --log-level debug
Running with Package Managers
Quiz MCP can be run directly with npx, pnpx, or bunx without manual installation:
# Using npx (npm)
npx quiz-mcp run --file ./my-quiz.json
# Using pnpx (pnpm)
pnpx quiz-mcp run --file ./my-quiz.json
# Using bunx (bun)
bunx quiz-mcp run --file ./my-quiz.json
# Run MCP server
npx quiz-mcp mcp
pnpx quiz-mcp mcp
bunx quiz-mcp mcp
# Run a quiz from URL (try example quizzes)
npx quiz-mcp run --url "https://raw.githubusercontent.com/karerckor/quiz-mcp/main/quiz-examples/javascript-fundamentals.jsonc"
pnpx quiz-mcp run --url "https://raw.githubusercontent.com/karerckor/quiz-mcp/main/quiz-examples/web-development.jsonc"
Standalone Mode (CLI)
Run a quiz directly from a local JSON file:
# Run a JavaScript quiz
pnpm quiz:js
# Run a Web Development quiz
pnpm quiz:web
Or run any custom file:
node bin/quiz-mcp run --file ./my-quiz.json --open
MCP Mode (AI Agent)
Start the MCP server to allow AI agents to connect:
node bin/quiz-mcp mcp
The server runs on port 3000 (default) or the port specified in your configuration.
MCP Client Setup
Configure Quiz MCP as an MCP server in your AI editor:
Claude Code
Add to ~/.claude/mcp.json:
{
"mcpServers": {
"quiz": {
"command": "npx",
"args": ["quiz-mcp", "mcp"],
"env": {}
}
}
}
Or using the local build:
{
"mcpServers": {
"quiz": {
"command": "node",
"args": ["/path/to/quiz-mcp/bin/quiz-mcp", "mcp"],
"env": {}
}
}
}
OpenCode
Add to ~/.opencode/mcp.json or in OpenCode settings under MCP Servers:
{
"mcpServers": {
"quiz": {
"command": "npx",
"args": ["quiz-mcp", "mcp"],
"disabled": false
}
}
}
Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"quiz": {
"command": "npx",
"args": ["quiz-mcp", "mcp"],
"env": {}
}
}
}
VSCode (with MCP Extension)
Add to your VSCode settings (JSON) or .vscode/mcp.json:
{
"mcpServers": {
"quiz": {
"command": "npx",
"args": ["quiz-mcp", "mcp"],
"env": {}
}
}
}
Development
-
Start the development server:
pnpm dev -
Run the CLI in dev mode:
pnpm quiz:js -
Run tests:
pnpm test # All tests (e2e + unit) pnpm test:e2e # Playwright e2e tests pnpm test:unit # Vitest unit tests -
Run Storybook:
pnpm storybook
Architecture
The project follows a modular SvelteKit architecture:
src/
├── cli/ # CLI entry points (unified quiz CLI)
│ ├── cli.ts # Main CLI with run/mcp commands
│ ├── mcp.ts # MCP server setup
│ └── args.ts # CLI argument parsing
├── lib/ # Shared logic and types
│ ├── components/ # Svelte components
│ │ ├── questions/# Question type components (8 types)
│ │ ├── ui/ # UI components (QuizProgress, QuestionNav, etc.)
│ │ └── QuizRenderer.svelte
│ ├── server/ # Server-side logic
│ │ └── sessions.ts # In-memory session management
│ ├── stores/ # Svelte stores
│ │ └── quiz.svelte.ts
│ ├── utils/ # Utilities
│ │ └── markdown.ts
│ └── types.ts # Comprehensive TypeScript types + Zod schemas
├── routes/ # SvelteKit routes
│ ├── api/ # API endpoints
│ │ ├── demo/ # Demo endpoint
│ │ └── quiz/ # Quiz session management endpoints
│ └── [quizId]/ # Quiz session routes
├── server/ # Custom Node.js server
│ └── index.ts # QuizServer implementation
├── stories/ # Storybook stories
└── hooks.* # SvelteKit hooks
Key Components
| Component | Purpose |
|---|---|
QuizRenderer | Main quiz container that orchestrates question rendering |
QuestionContainer | Wrapper for individual questions with validation |
SingleChoice | Single selection (radio buttons) |
MultipleChoice | Multiple selection (checkboxes) |
RemoveExtra | Error-finding question type |
Order | Drag-and-drop ordering |
Match | Pair matching |
Text | Free-form text input |
Input | Single-line text input |
InputList | Dynamic input list |
Server Architecture
The QuizServer class provides:
- Session Management: In-memory session storage with expiration
- Session Lifecycle: Create, poll status, cancel sessions
- Result Collection: Answers, time spent, metadata
- Webhook Support: Optional POST results to external URL
Session Flow
┌─────────────────┐ ┌────────────────┐ ┌─────────────────┐
│ AI Agent/MCP │────▶│ QuizServer │────▶│ SvelteKit App │
│ (create quiz) │ │ (sessions) │ │ (web UI) │
└─────────────────┘ └────────────────┘ └─────────────────┘
│ │ │
│ sessionId/quizId │ │
│◀─────────────────────│ │
│ │ │
│ │ user completes │
│ │◀───────────────────────┘
│ poll status │ │
│─────────────────────▶│ │
│ │ │
│ results (optional) │ │
│◀─────────────────────│ │
MCP Tools
get_quiz_format
Returns the JSON schema and examples for creating valid quiz content.
Input: {}
Output: JSON schema for QuizData and example question objects.
start_quiz
Starts a new quiz session.
Input:
{
"quiz": "QuizData object or JSON string",
"config": {
"theme": "light|dark|auto",
"timerEnabled": boolean,
"shuffleQuestions": boolean,
"shuffleOptions": boolean,
"webhook": "url"
},
"open": boolean // (Optional) Auto-open browser
}
Output:
{
"ok": true,
"openUrl": "http://localhost:3000/quiz/session-id",
"quizId": "...",
"sessionId": "...",
"expiresAt": "..."
}
get_quiz_status
Checks the status of an active session.
Input:
{
"quizId": "string",
"sessionId": "string",
"includeAnswers": boolean // (Optional) Include detailed results
}
Output:
{
"status": "active|completed|expired|not_found|error",
"startedAt": "ISO timestamp",
"completedAt": "ISO timestamp (if completed)",
"progress": {
"answered": 5,
"total": 10,
"percentage": 50
},
"answers": {
/* Only if completed and includeAnswers=true */
}
}
cancel_quiz
Terminates an active session.
Input:
{
"quizId": "string",
"sessionId": "string",
"reason": "string"
}
Output:
{
"ok": true,
"message": "Session cancelled",
"cancelledAt": "ISO timestamp"
}
Quiz Data Format
The QuizData object structure:
{
"title": "Quiz Title",
"description": "Optional description",
"version": "1.0.0",
"metadata": {
"author": "Author Name",
"difficulty": "easy|medium|hard",
"estimatedTime": 15,
"tags": ["tag1", "tag2"]
},
"questions": [
{
"id": "unique-id",
"type": "single|multiple|remove-extra|order|match|text|input|input-list",
"question": "Question text (Markdown supported)",
"explanation": "Explanation shown after submission",
"points": 1,
"required": true,
"options": ["Option A", "Option B"], // or MatchOptions/InputListOptions
"attachments": [{ "type": "image", "url": "..." }],
"validation": { "minLength": 10, "maxLength": 500 }
}
]
}
Question Type Options
Simple Options (single, multiple, remove-extra, order):
{
"options": ["Option A", "Option B", "Option C"]
}
Match Options:
{
"options": {
"left": ["Cat", "Dog"],
"right": ["Meow", "Woof"]
}
}
Input List Options:
{
"options": {
"minItems": 1,
"maxItems": 5,
"placeholder": "Enter item...",
"addButtonText": "Add Item"
}
}
Configuration
CLI Config File (config.json)
{
"layout": {
"title": "Custom Quiz Title",
"logo": "/logo.png",
"hideThemeSwitcher": false,
"hideLanguageSwitcher": false
},
"theme": "auto",
"shuffleQuestions": false,
"shuffleOptions": false,
"allowBackNavigation": true,
"showProgress": true,
"showQuestionNumbers": true,
"timerEnabled": false,
"timerDuration": 30,
"language": "en",
"webhook": "https://your-webhook.com/results",
"analytics": {
"enabled": true,
"provider": "plausible",
"trackingId": "..."
}
}
Integration Guide for Agents
- Discovery: Call
get_quiz_formatto understand how to structure a quiz. - Creation: Generate a valid
QuizDataobject based on the user's topic or request. - Execution: Call
start_quizwith the generated data. - Handoff: Provide the
openUrlto the user so they can take the quiz. - Monitoring: Use
get_quiz_statusto track progress if needed, or wait for the user to confirm completion.
License
MIT
Related Servers
MCP Goodnews
An MCP application that delivers curated positive and uplifting news stories using NewsAPI and Cohere LLM.
Atris MCP for Audius
Access the Audius music platform via LLMs, with 105 tools covering most of the Audius Protocol API.
BSC MultiSend MCP
Perform bulk BNB and BEP20 token transfers on the BNB Smart Chain (BSC).
Medical Terminologies MCP
Unified access to global medical terminologies: ICD-11, SNOMED CT, LOINC, RxNorm, MeSH. 27 tools for medical coding, terminology lookup, and crosswalk mappings.
Scenario Word
A server for the scenario-word MCP, built with the mcp-framework.
EduBase
Interact with EduBase, a comprehensive e-learning platform with advanced quizzing, exam management, and content organization capabilities
YouTube Playlist Generator MCP Server
A Model Context Protocol (MCP) server that enables AI applications to search for YouTube music videos and manage playlists using the official YouTube Data API v3.
MCP Simple Timeserver
Provides current local time, UTC time, and timezone information.
Trading MCP Server
An intelligent trading assistant that fetches live stock prices using the Yahoo Finance API.
Tokyo WBGT MCP Server
Provides real-time and forecast WBGT (Heat Index) data for Tokyo from Japan's Ministry of the Environment.