Quiz MCP

Instead of generating HTML forms as artifacts or asking questions one-by-one in chat, the model describes a quiz as JSON, the user fills it in athttp://localhost:<port>, and the answers flow back to the model as structured data.

Useful for teachers building quizzes with AI, researchers running structured interviews, or any agent that needs real input from a human.

Try the demo quiz (no install, no clone)

Run the bundled 7-question JavaScript basics quiz straight from GitHub:

npx @quiz-mcp/runner \ --url https://raw.githubusercontent.com/karerckor/quiz-mcp/main/demo/js-quiz.json \ --output ./answers.json \ --open

--openlaunches the URL in the system browser. Answers are written to./answers.jsonwhen you submit.

Once connected, the model gains four tools:start_quiz,get_answers,get_quiz_format, andstop_runner.

Add to.mcp.jsonin your project root (or~/.claude.jsonfor user-wide):

{ "mcpServers": { "quiz-mcp": { "type": "stdio", "command": "npx", "args": ["-y", "@quiz-mcp/cli", "mcp"] } } }

Add toopencode.json(project) or~/.config/opencode/opencode.json(global):

{ "$schema": "https://opencode.ai/config.json", "mcp": { "quiz-mcp": { "type": "local", "command": ["npx", "-y", "@quiz-mcp/cli", "mcp"], "enabled": true } } }

Open the MCP settings panel in Kilo Code (MCP Servers → Edit Global MCP) and add:

{ "mcpServers": { "quiz-mcp": { "command": "npx", "args": ["-y", "@quiz-mcp/cli", "mcp"] } } }

The samecommand/argspair works for any MCP client that follows the standardmcpServersshape (Claude Desktop, Cursor, Windsurf, …).

If you don't want to install anything locally, there is a hosted, OAuth-protected version of quiz-mcp running on Cloudflare Workers:

https://quiz-mcp-oauth.karerckor.workers.dev/mcp

It exposes the same tools as the local server, plusget_quizzesandcleanup_quizfor managing per-user state. Each user gets an isolated quiz workspace; login is handled via WorkOS AuthKit on the first tool call.

Note:answers are persisted to Cloudflare KV, which is eventually consistent. After a user submits a quiz,get_answersmay briefly return empty or stale data — wait a few seconds and retry if the model reports missing answers.

Register the remote server with theclaudeCLI (this stores it in~/.claude.json):

claude mcp add --transport http quiz-mcp-remote https://quiz-mcp-oauth.karerckor.workers.dev/mcp

Or add it manually to.mcp.json(project) /~/.claude.json(user-wide):

{ "mcpServers": { "quiz-mcp-remote": { "type": "http", "url": "https://quiz-mcp-oauth.karerckor.workers.dev/mcp" } } }

On the first call (e.g.start_quiz) Claude Code will open your browser for the OAuth flow; the access token is cached afterwards. Run/mcpinside Claude Code to inspect connection state or re-authenticate.

Want to host your own instance? Seeapps/remote-mcp-oauth/README.mdfor the full setup (Cloudflare KV namespaces, WorkOS secrets,wrangler deploy).

# scaffold a new quiz skeleton → ./javascript-basics.quiz.json npx @quiz-mcp/cli create "JavaScript basics" # serve it in a browser and write answers to a file npx @quiz-mcp/runner --file ./javascript-basics.quiz.json --output ./answers.json --open

npx @quiz-mcp/runner \ --url https://example.com/quiz.json \ --on-complete https://example.com/hooks/quiz \ --output ./answers.json

git clone https://github.com/karerckor/quiz-mcp.git cd quiz-mcp pnpm install

{ "id": "my-quiz-1", "title": "Quiz title", "description": "Optional description", "questions": [ / Question[] / ] }

single_choice,multiple_choice,short_text,long_text,dropdown,fill_gaps,match,scale,sorting,upload

pnpm schema:gen # writes schema/quiz.schema.json pnpm schema:check # validates the generated schema with AJV

The schema is also available at the canonical URL embedded in the file:https://raw.githubusercontent.com/karerckor/quiz-mcp/main/schema/quiz.schema.json

- apps/cli/README.md— MCP tools, lifecycle behaviour, CLI commands
- apps/runner/README.md— standalone runner CLI flags, exit codes, architecture
- apps/remote-mcp-oauth/README.md— hosted remote MCP server, OAuth setup, Cloudflare deployment
- packages/core/README.md— domain schemas, grading API, validation, adding question types
- packages/runner-api/README.md— REST endpoints, SSR server options,QuizServiceinterface, theming
- packages/runner-ui/README.md— client bundle internals, Vite manifest, custom deployments
- packages/web-components/README.md—<quiz-player>element API, events, theming, framework integration

Real-time stock heatmaps and investment tools delivered as interactive React components.