Study Buddy

Turn your notes and past papers into a focused, local AI study system.

An MCP server that gives Claude structured access to your study material, so it can teach, quiz, and drill you on your own content, and remember how you did.

Quick Start · How it Works · Tools & Prompts · Extend · Full Tutorial

✨ Why Study Buddy

LLMs can reason. They can't reach into your world: your notes, your past papers, your progress.

Study Buddy closes that gap with the Model Context Protocol (MCP). You drop material into two folders. Your MCP client (Claude Desktop, Cursor, anything MCP-compatible) can now:

📚 Learn

Teach any topic from your material, in any style you ask for: Feynman, Socratic, exam-cram, ELI5, or anything else.

🧠 Practice

Grounded quizzes from your notes. PYQ-pattern practice: real past questions verbatim, or new questions in that exact style.

📈 Track

Local SQLite tracks mastery per topic across sessions. Weakest topics surface first. Archive what you've mastered.

Built to also serve as a complete reference for the MCP protocol: every primitive, exercised with production-shaped code.

⚡ Quick Start

# 1. Clone
git clone https://github.com/eshitakundu/study-buddy.git
cd study-buddy

# 2. Install
uv sync

# 3. Drop notes into materials/content/ and past papers into materials/pyqs/

# 4. Verify the server with the MCP Inspector
uv run mcp dev study_buddy.py

Then connect it to Claude Desktop and start a chat:

"Discover topics in my materials, register the real ones, then quiz me on the weakest one."

🧬 How it Works

flowchart LR
    A[📁 materials/<br/>content + pyqs] --> B[⚙️ study_buddy.py<br/>MCP server]
    B --> C[💾 SQLite<br/>topics + results]
    B <-->|stdio| D[🤖 Claude Desktop]
    D -->|calls tools| B
    D -->|renders prompts| B
    D -->|reads resources| B

The three MCP primitives, doing real work

Plus typed inputs via Pydantic Field, persistent state via SQLite, and path-traversal-safe file access.

📁 Project Structure

study-buddy/
├── 📦 study_buddy.py         ← the entire server, one file
├── 🗄️  study.db              ← auto-created SQLite tracker
├── 📚 materials/
│   ├── content/            ← notes, slides, textbook extracts
│   ├── pyqs/               ← previous-year question papers
│   └── archive/            ← files you've moved aside
├── 🖼️  assets/banner.png
├── pyproject.toml
├── uv.lock
└── README.md

Subfolders and study.db are auto-created on first run.

📥 Setup

• Python 3.10+
• uv: fast Python package manager
• MCP-compatible client: Claude Desktop, Cursor, Cline, etc.
• Node.js: only for the MCP Inspector via mcp dev

Pinned dependencies:

• mcp[cli]>=1.27,<2: the <2 bound matters; SDK v2 changes import paths
• pypdf
• python-docx

git clone https://github.com/eshitakundu/study-buddy.git
cd study-buddy
uv sync

Notes (materials/content/):

dbms-notes.md
transactions.pdf
normalization-slides.docx
er-diagram.png

Past papers (materials/pyqs/):

dbms-midterm-2024.pdf
dbms-final-2023.txt
operating-systems-pyq.docx

Files moved via archive_files land in materials/archive/.

🧪 Run and Test

uv run mcp dev study_buddy.py

Opens the MCP Inspector in your browser (via npx). List and call every tool, read resources, and preview rendered prompts, all before touching your client.

⚠️ Gotcha: if node stays alive on port 6277 after the Inspector closes, the next mcp dev fails with Proxy Server PORT IS IN USE. Fix on Windows:

Get-Process node | Stop-Process -Force

🔌 Connect to Claude Desktop

Config file:

• Windows → %APPDATA%\Claude\claude_desktop_config.json
• macOS → ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "study-buddy": {
      "command": "C:\\Users\\<you>\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "C:\\Users\\<you>\\path\\to\\study-buddy",
        "run",
        "study_buddy.py"
      ]
    }
  }
}

🔑 Three things that trip everyone up:

1. Use absolute paths: Claude Desktop's working directory isn't your project folder.
2. On Windows, escape backslashes as \\.
3. Fully quit Claude Desktop from the system tray before reopening. Closing the window isn't enough.

Debug logs → %APPDATA%\Claude\logs\mcp-server-study-buddy.log

🔧 Tools

📖 Resources

💡 Important: in Claude Desktop, resources are user-attached, not auto-fetched. Tools are model-initiated. Design accordingly.

💬 Prompts

🎓 study

Teach a topic from your content in any style.

topic:  normalization
style:  feynman

Styles: default, feynman, socratic, eli5, summary, exam-cram, or anything else the model can interpret.

🏫 study_all

Walk through every active registered topic.

style:  default
order:  weakest_first | registered

📝 quiz

Grounded quiz drawn only from your content. One question at a time. Results logged automatically.

topic:  functional dependencies
n:      5

🎯 pyq_test

Real past questions or new ones matching the paper's style.

topic:  normalization
mode:   ask | verbatim | style
n:      5

🛡️ Safety

• All file access confined to materials/content/, materials/pyqs/, materials/archive/
• Paths validated via Path.is_relative_to: blocks ../../.env traversal
• Topic strings normalized and fuzzy-matched against registered rows: no silent row creation
• Every input bound (n, days, max_results) enforced via Pydantic Field metadata

📄 Supported Files

⚠️ Scanned PDFs have no extractable text. pypdf returns empty. OCR (Tesseract) or a text-based version before dropping in.

🎬 Example Session

1. Discover topics from my material.
2. Register normalization and functional dependencies.
3. Teach me normalization in exam-cram style.
4. Quiz me on normalization with 5 questions.
5. Show my weakest topics.
6. Give me a PYQ-style test on functional dependencies.

The client chains discovery → registration → retrieval → quiz → logging, all against your own material.

🚀 Extend

Same MCP scaffolding, different domain:

The recipe:

safe data access
+ tools           (actions)
+ resources       (browsable context)
+ prompts         (workflows)
+ persistent state (SQLite)
= a practical MCP server

🛠️ Built With

• Official MCP Python SDK: mcp[cli] with FastMCP
• SQLite: persistent state (stdlib)
• Pydantic: typed inputs (via the SDK)
• pypdf, python-docx: file extraction
• uv: dependency management

📜 License

MIT © Eshita Kundu (see LICENSE).

Built for the Codédex Monthly Challenge, June 2026

⭐ Star if this taught you something · 🐛 Issues · 💬 Discussions