Question Bank MCP Server

An MCP server for managing K-12 assessment question banks with IRT metadata. Build, organize, and search test questions with full Bloom's taxonomy classification, difficulty calibration, and topic tagging — all through natural language with Claude.

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude connect to external tools and data sources. This server gives Claude the ability to create, manage, and query question banks directly — no copy-pasting or manual data entry.

Related MCP server: DocuMCP

Features

• Question CRUD — Create, read, update, and delete questions with full metadata

• Question types — Multiple choice, true/false, short answer, and essay

• Bloom's taxonomy — Classify questions across all 6 cognitive levels (remember through create)

• Difficulty calibration — Continuous 0.0–1.0 scale with easy/medium/hard bucketing

• IRT metadata — discrimination_index, times_used, times_correct, avg_time_seconds

• Topic hierarchy — Organize questions into nested topics within banks

• Flexible tagging — Tag questions with arbitrary labels for cross-cutting categorization

• Search and filter — Query by type, difficulty range, Bloom's level, topic, tags, status, or free text

• Bulk activation — Move multiple questions from draft to active in one call

• AI suggestions — Get question ideas for a topic at specified difficulty and Bloom's levels

• Bank statistics — Detailed breakdowns by type, difficulty, Bloom's level, and topic

Quick Start

1. Clone and install

git clone https://github.com/woodstocksoftware/question-bank-mcp.git
cd question-bank-mcp
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "question-bank": {
      "command": "/path/to/question-bank-mcp/venv/bin/python",
      "args": ["/path/to/question-bank-mcp/run_server.py"]
    }
  }
}

Then restart Claude Desktop.

3. Configure Claude Code

claude mcp add question-bank /path/to/question-bank-mcp/venv/bin/python /path/to/question-bank-mcp/run_server.py

4. Start using it

Ask Claude things like:

"Create a question bank for AP Biology"

"Add a topic for Cellular Respiration"

"Create a multiple choice question about the Krebs cycle at the Analyze level"

"Show me all hard questions tagged as 'midterm'"

"What are the statistics for my question bank?"

Tool Reference

Question Bank Tools

create_question_bank

Create a new question bank for a course or subject area.

list_question_banks

List all question banks with their question and topic counts. No parameters.

get_bank_statistics

Get detailed statistics for a question bank, including breakdowns by question type, difficulty bucket, Bloom's level, and topic.

Topic Tools

create_topic

Add a topic to organize questions within a bank. Supports hierarchical nesting via parent_topic_id.

list_topics

List all topics in a question bank with question counts.

Question Tools

create_question

Create a new question with full metadata. Questions start in draft status.

get_question

Retrieve a question by ID with all metadata.

update_question

Update any field on an existing question, including changing its status.

delete_question

Permanently delete a question.

search_questions

Search and filter questions across banks with multiple criteria.

activate_questions

Bulk-activate questions, moving them from draft to active status.

suggest_questions

Get AI-friendly suggestions for new questions to create, based on topic and constraints.

Resources

Question Schema

Fields

Difficulty Buckets

Bloom's Taxonomy Levels

Usage Examples

Build a math question bank

"Create a question bank called 'Algebra 2' for grades 10-11"

"Add topics for Polynomials, Quadratic Equations, and Exponential Functions"

"Create 3 multiple choice questions about factoring polynomials at the Apply level, difficulty 0.4–0.6"

"Activate all the questions we just created"

Search by difficulty and Bloom's level

"Find all hard questions at the Evaluate or Create level"

"Search for questions about quadratics with difficulty above 0.7"

"Show me all draft questions tagged 'final-exam'"

Get suggestions for gaps

"What are the statistics for my Algebra 2 bank?"

"Suggest 5 easy Remember-level questions about exponential growth"

"We need more Analyze-level questions — suggest some for Quadratic Equations"

Architecture

┌─────────────────────────────────────────────┐
│             Claude Desktop / Code            │
│               (MCP Client)                   │
└──────────────────┬──────────────────────────┘
                   │ stdio
┌──────────────────▼──────────────────────────┐
│  run_server.py                               │
│  └─ src/question_bank/server.py              │
│     ├─ 12 tools  (@mcp.tool)                │
│     ├─ 2 resources (@mcp.resource)           │
│     └─ Markdown-formatted responses          │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│  src/question_bank/database.py               │
│  ├─ question_banks     (top-level containers)│
│  ├─ topics             (hierarchical)        │
│  ├─ questions          (content + IRT)       │
│  ├─ question_topics    (many-to-many)        │
│  └─ question_tags      (many-to-many)        │
└──────────────────┬──────────────────────────┘
                   │
              data/question_bank.db (SQLite)

QTI 3.0 Compatibility

The question schema is designed with QTI 3.0 compatibility in mind. The data model supports the core fields needed for QTI export (question types, correct answers, options, metadata), but import/export is not yet implemented. This is a planned future enhancement.

Testing

No automated test suite yet. To verify the database layer works correctly:

python -m src.question_bank.database

To confirm the server starts:

python run_server.py

The server runs on stdio transport, so it will appear to hang (it's waiting for MCP client input). Press Ctrl+C to stop.

Contributing

Contributions are welcome! This project is in early development. Areas that could use help:

• Automated tests (pytest)

• QTI 3.0 import/export

• Additional question types

• CI/CD pipeline

License

MIT

Built by Jim Williams | GitHub