quizzard-mcp 1.0.0

A multi-source trivia and quiz MCP server

Quizzard

Quizzard is an MCP server for trivia and quizzing enthusiasts. The overarching goal of the project is to have as many useful features to help quizzers stay on top of their game. A number of popular quizzing resources have been integrated (see section titled 'Data Soruces and Attribution') -

• Open Trivia DB
• J! Archive
• user-uploaded PDFs, and
• user-input URLs (such as Wikipedia pages). Although these provide sufficient breadth and depth across common trivia question categories, it is crucial to extend this list to include a few other commonly used ones (Jetpunk, Sporcle, etc.; these currently have Cloudflare-related restrictions), as well as handling the user's presence and statistics on these platforms on their behalf. A number of core features have been implemented as tools (see sections 'Features' and 'Tools' for complete list) -
• persistent progress tracking
• weak area detection
• personalised recommendations.

The MCP client chosen for testing has been Claude Desktop on Windows; as yet untested on other clients (though incompatibility with others seems unlikely). Kindly report bugs, feature requests, and any relevant thoughts through issues.

---

Features

• Multiple quiz sources - OpenTDB (over 4k questions), Jeopardy! (over 200k clues), and any custom source you add
• Custom sources - ingest PDFs, webpages, or manually enter questions. You can, say, quiz yourself on your own study material
• Mixed quizzes - draw questions from multiple sources in one session
• Progress tracking - every session is saved to a local SQLite database
• Weak area detection - identifies categories where your accuracy is lowest
• Personal bests - tracks your best score per category and difficulty
• Smart recommendations - suggests what to play next based on your history

---

Installation

1. Clone the repo

git clone https://github.com/hrmtsh2/quizzard.git
cd quizzard

2. Create and activate a virtual environment

python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux [NOT TESTED YET]
source venv/bin/activate

3. Install dependencies

Install through pip freeze-generated requirements.txt -

pip install -r requirements.txt

Alternatively, just install the most critical ones -

pip install fastmcp httpx beautifulsoup4 pdfplumber

4. Configure your MCP client

For Claude Desktop, for example, add the following to your claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json [NOT TESTED YET]

{
  "mcpServers": {
    "quizzard": {
      "command": "C:/path/to/quizzard/venv/Scripts/python.exe",
      "args": ["C:/path/to/quizzard/server.py"]
    }
  }
}

Replace paths with your actual project path. Make sure to use forward slashes on Windows!

5. For Claude Desktop - Restart Claude Desktop

Quizzard will initialise automatically on first run, creating a local database at ~/.quizzard/quizzard.db.

---

Usage

Just talk to the LLM naturally (again, tested on Claude Sonnet 4.6). Some sample prompts to get you started -

"Quiz me on geography, medium difficulty, 10 questions"
"Quiz me on Jeopardy! science clues"
"Enable Jeopardy as a source"
"What are my weak areas?"
"What should I play next?"
"Ingest this PDF and quiz me on it"
"Quiz me on a mix of OpenTDB and Jeopardy"
"Show my recent sessions"
"What sources do I have?"

---

Tools Implemented

Tool	Description
quiz_me	Start a tracked quiz session
submit_quiz_results	Save results after a quiz (called automatically)
get_questions	Browse/preview questions without starting a session
start_session	Enable deduplication so you never see repeat questions
list_categories	List available categories for a source
search_categories	Search categories by keyword
enable_jeopardy	Download and import the Jeopardy! dataset (~75MB, one-time)
ingest_pdf	Extract questions from a PDF and save as a custom source
ingest_url	Extract questions from a webpage and save as a custom source
save_custom_questions	Manually save a set of questions as a custom source
list_sources	List all available quiz sources
recommend_quiz	Get a personalised quiz recommendation based on your history
my_weak_areas	See your weakest categories (min 5 attempts)
my_personal_bests	See your best scores per category and difficulty
my_recent_sessions	See your recent quiz sessions
my_stats	See accuracy stats across all categories

---

Architecture

Quizzard is built to be source-agnostic, even with the few sources included so far. Each quiz source implements a common interface, so server.py never needs to know which source it's talking to.

quizzard/
├── server.py          # core FastMCP server with all the tools
├── client.py          # httpx wrapper for external APIs
├── db.py              # SQLite database for storing sessions, attempts, stats
└── sources/
    ├── base.py        # QuizSource class (the common interface)
    ├── opentdb.py     # Open Trivia Database
    ├── jeopardy.py    # Jeopardy! dataset (local SQLite)
    └── user.py        # User-defined sources

Adding a new source ideally means creating one file in sources/ and registering it in question_sources in server.py, with no other changes elsewhere.

User data is stored locally at:

~/.quizzard/
├── quizzard.db          # all sessions, attempts, stats, custom questions
└── data/
    └── combined_season1-41.tsv   # Jeopardy dataset (downloaded on first enable)

---

Data Sources & Attribution

• General trivia — Open Trivia Database, licensed under CC BY-SA 4.0
• Jeopardy! clues — Dataset compiled by jwolle1, sourced from J! Archive
• Jeopardy! is a registered trademark of Jeopardy Productions, Inc. This project is not affiliated with or endorsed by Jeopardy Productions, Inc.

This project is for personal, non-commercial use only.

---

For MCP Registry to recognise this server - mcp-name: io.github.hrmtsh2/quizzard_mcp