📚 study-mcp

A Model Context Protocol (MCP) server that turns video transcripts and study materials into a searchable, AI-powered knowledge base — directly inside Claude Desktop.

---

✨ What it does

Paste a video transcript or point to a PDF, slide deck, DOCX, or image and instantly:

• 🎬 Ingest video transcripts — paste raw text or load .srt/.vtt caption files; timestamps are preserved so you can jump back to the exact moment in the video
• 🔍 Search semantically — ask questions in natural language across all your materials, powered by local embeddings (no API cost)
• 🎯 Generate quizzes — sample representative context from any material so Claude can quiz you on it
• 🧠 Summarize & create flashcards — saved directly to Notion
• 📊 Track your library — list materials, inspect overviews, view stats, delete what you no longer need

Everything runs locally by default (ChromaDB + HuggingFace embeddings). Set a single environment variable to switch to pgvector on Supabase/Postgres.

---

🧰 Tech Stack

Layer	Technology
Language	Python 3.13
MCP server	MCP Python SDK (FastMCP)
Embeddings	sentence-transformers + HuggingFace models (local inference, PyTorch)
Vector stores	ChromaDB (local) · pgvector on Supabase/Postgres (cloud)
Document parsing	Docling (PDF, DOCX, PPTX, HTML, images) + native SRT/VTT parser
Integrations	Notion API (notion-client)
Configuration	pydantic-settings (typed, env-based)
Tooling	Poetry · pytest (+coverage) · ruff · mypy --strict · pre-commit · commitizen
CI	GitHub Actions (lint, type check, tests on every push/PR)

---

🏗️ Architecture

study-mcp/
├── src/study_mcp/
│   ├── core/
│   │   ├── config.py       # Settings via environment variables (pydantic-settings)
│   │   ├── embeddings.py   # sentence-transformers, local inference, E5 prefixing
│   │   ├── chunker.py      # Heading → paragraph → sentence-aware chunking
│   │   └── transcript.py   # SRT/VTT parser with timestamp preservation
│   ├── db/
│   │   ├── __init__.py     # VectorRepository protocol + backend auto-detection
│   │   ├── chroma.py       # Local vector store (ChromaDB, zero setup)
│   │   └── pgvector.py     # Cloud vector store (Supabase/Postgres, HNSW index)
│   ├── tools/
│   │   ├── ingest.py       # File & raw-text ingestion (Docling + native parsers)
│   │   ├── search.py       # Semantic search
│   │   ├── materials.py    # Overview, quiz context, stats, deletion
│   │   ├── list_materials.py
│   │   └── notion.py       # Notion integration (summaries & flashcards)
│   └── server.py           # FastMCP server: tools, resource, prompt, lifespan
├── tests/                  # 60 tests, ~96% coverage, no model download needed
└── docs/
    └── claude_desktop_config.json

Design highlights:

• Repository pattern — both vector backends implement the same VectorRepository protocol; the backend is chosen at startup from DATABASE_URL with no code changes.
• E5 query/passage prefixing — intfloat/multilingual-e5-* models are trained with query: / passage: prefixes; applying them measurably improves retrieval quality. Applied automatically when an E5 model is configured.
• Sentence-aware chunking — text is split by heading, then paragraph, then grouped by whole sentences with sentence-level overlap. Chunks never cut a word or sentence in half.
• Idempotent ingestion — material_id is a SHA-256 content hash, so re-ingesting the same material is a no-op (already_indexed) instead of a duplicate.
• Timestamp-aware transcripts — SRT/VTT cues are grouped into paragraphs by speech pauses; search results on transcripts carry a start_time so you can jump back into the video.

---

🛠️ Available Tools

Tool	Description
ingest_text_tool	Ingest raw text — e.g. a pasted video transcript — into the vector store
ingest_file_tool	Convert and index a file: PDF, DOCX, PPTX, HTML, images, .txt, .md, .srt, .vtt
search_tool	Semantic search across all indexed materials (optionally scoped to one)
list_materials_tool	List all indexed materials
get_material_overview_tool	Preview the first chunks of a material before summarizing or quizzing
generate_quiz_context_tool	Sample chunks spread across a material so Claude can write quiz questions
study_stats_tool	Totals: materials, chunks, chunks per material
delete_material_tool	Remove a material and all of its chunks
save_summary_tool	Save a summary to Notion
save_flashcards_tool	Save Q&A flashcards to Notion
create_quiz_tool	Create an interactive quiz page in Notion (open or multiple-choice, answer in Notion then paste back for checking)

The three Notion tools also accept related_pages (a list of notion_url values from earlier saves in the same conversation) to link a new page to related materials via Notion's native mentions - see docs/NOTION_SETUP.md.

The server also exposes an MCP resource (study://materials, the current library as JSON) and a prompt (study_prompt, a ready-made study-plan workflow for any material).

---

🚀 Quick Start

1. Clone and install

git clone https://github.com/italoo97/study-mcp.git
cd study-mcp
poetry install

2. Configure environment

cp .env.example .env

All variables have sensible defaults — the server works out of the box with ChromaDB and no external services. See .env.example for every option.

3. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (see docs/claude_desktop_config.json for a full example):

{
  "mcpServers": {
    "study-mcp": {
      "command": "poetry",
      "args": [
        "--directory", "/absolute/path/to/study-mcp",
        "run", "python", "-m", "study_mcp.server"
      ],
      "env": {
        "CHROMA_PATH": "/absolute/path/to/study-mcp/chroma_db"
      }
    }
  }
}

⚠️ Claude Desktop launches the server from its own working directory, so relative paths (like the .env file or the default ./chroma_db) won't resolve to the project folder. Set CHROMA_PATH to an absolute path as above, and pass any other variables (NOTION_TOKEN, DATABASE_URL, ...) in the env block — see docs/claude_desktop_config.json for a complete example.

Vector backend is auto-detected:

• DATABASE_URL empty → ChromaDB locally (zero setup)
• DATABASE_URL set → pgvector on Supabase/Postgres (free tier works; table and HNSW index are created automatically)

4. Restart Claude Desktop

The tools appear automatically.

---

🎬 Ingesting video transcripts

The main workflow this server was built for:

1. Open a video (YouTube, a recorded lecture, a course platform) and copy its transcript — or download the captions as .srt/.vtt.
2. Paste it into Claude: "Ingest this transcript as 'Linear Algebra — Lecture 3': ..." → Claude calls ingest_text_tool.
3. Ask anything: "According to my lecture, what is an eigenvector?" → search_tool returns the most relevant passages, each with a start_time when available, so you can jump back to that moment in the video.
4. Study actively: "Quiz me on this lecture" → generate_quiz_context_tool samples passages spread across the whole material and Claude writes the questions.

.srt/.vtt files are parsed natively: cue numbers and markup are stripped, consecutive cues are merged into paragraphs at natural speech pauses, and paragraph start times are preserved as metadata.

---

🧠 Embedding Models

Set EMBEDDING_MODEL to any sentence-transformers compatible model:

Model	Languages	Dims
intfloat/multilingual-e5-small (default)	PT + EN + 90 more	384
intfloat/multilingual-e5-base	PT + EN + 90 more	768
BAAI/bge-small-en-v1.5	EN only	384

Update EMBEDDING_DIM to match — the server validates the dimension at startup and fails fast on a mismatch.

---

📋 Notion Setup (optional)

Only needed for save_summary_tool and save_flashcards_tool. Full walkthrough (including a script that creates the database for you) in docs/NOTION_SETUP.md.

Quick version:

1. Create an integration at notion.so/my-integrations
2. Create the database — either run poetry run python scripts/create_notion_database.py <parent_page_id> (creates it with the right schema and shares it automatically), or create it by hand with these properties: Name (Title), Type (Select), Material (Rich text), Tags (Multi-select) — then share it with your integration manually.
3. Set NOTION_TOKEN and NOTION_DATABASE_ID in the env block of your Claude Desktop config (not .env — see docs/claude_desktop_config.json).

---

💡 Example usage in Claude

"Ingest this transcript as 'ML Course — Gradient Descent': [pasted transcript]"

"Ingest this file: /Users/me/Downloads/algorithms_lecture.pdf"

"Search my materials: what is dynamic programming?"

"Give me an overview of material a1b2c3d4"

"Quiz me with 10 questions about my gradient descent lecture"

"Summarize it and save to Notion with tags: ML, optimization"

"Show my study stats"

---

🔧 Development

poetry install

poetry run task lint        # ruff check
poetry run task format      # ruff format
poetry run task type_check  # mypy --strict
poetry run task test        # pytest (60 tests, coverage gate at 80%)

The test suite runs without downloading any embedding model — embeddings are faked with deterministic vectors and the repository layer is tested against an in-memory double plus a real ChromaDB instance in a temp directory.

CI (GitHub Actions) runs lint, strict type checking, and the full test suite on every push and PR.

---

📄 License

MIT