MCP Tutor Server (Python)

An AI tutoring system that runs as a Model Context Protocol (MCP) server, allowing Claude to access and interact with your local educational materials to provide personalized tutoring based on your actual course content.

Features

• Privacy First: All your educational materials stay on your local machine
• Universal Format Support: Works with PDFs, Markdown, and text files
• Smart Search: Find concepts and explanations across all your materials
• Interactive Learning: Generate quizzes, summaries, and detailed explanations
• Resource Access: Claude can read full documents for comprehensive answers

What It Does

The tutor server provides Claude with 5 powerful tools:

1. explain_concept - Search for and explain specific concepts from your materials
2. search_materials - Full-text search across all documents with context
3. summarize_topic - Generate brief or detailed summaries of topics
4. generate_quiz - Create practice questions at various difficulty levels
5. list_topics - Browse all available educational materials

All your documents are also exposed as resources, allowing Claude to read complete files when needed.

Installation

Prerequisites

• Python 3.10 or higher
• Claude Desktop app

Setup

1. Clone or download this directory:

cd tutor-mcp-python

2. Install the package:

pip install -e .

Or using uv (recommended):

uv pip install -e .

3. Configure Claude Desktop:

Edit your Claude Desktop config file:

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

Add the tutor server:

{
  "mcpServers": {
    "tutor": {
      "command": "python",
      "args": ["-m", "tutor_mcp.server"],
      "env": {
        "TUTOR_MATERIALS_PATH": "/absolute/path/to/materials"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "tutor": {
      "command": "tutor-mcp",
      "env": {
        "TUTOR_MATERIALS_PATH": "/absolute/path/to/materials"
      }
    }
  }
}

4. Add your educational materials:

Create a materials directory and add your files:

materials/
├── computer-science/
│   ├── algorithms.pdf
│   └── data-structures.md
├── mathematics/
│   └── calculus-notes.txt
└── physics/
    └── quantum-mechanics.pdf

5. Restart Claude Desktop

Usage

Once configured, you can ask Claude questions about your materials:

• "Explain the concept of binary search trees based on my materials"
• "Search my notes for information about quantum entanglement"
• "Generate a quiz on recursion with 5 medium difficulty questions"
• "Summarize what my materials say about Big O notation"
• "What topics do I have materials for?"

Claude will use the tutor server to access your files and provide personalized answers based on your actual course content.

Supported File Formats

• .txt - Plain text files
• .md, .markdown - Markdown files
• .pdf - PDF documents (text extraction)

Configuration

Environment Variables

• TUTOR_MATERIALS_PATH - Path to your educational materials directory (default: ./materials)

Materials Directory

Organize your materials however you like. The server will:

• Recursively scan all subdirectories
• Index all supported file types
• Make them searchable and accessible to Claude

Development

Running from Source

python -m tutor_mcp.server

Running Tests

pip install -e ".[dev]"
pytest

Project Structure

tutor-mcp-python/
├── src/
│   └── tutor_mcp/
│       ├── __init__.py
│       └── server.py          # Main server implementation
├── materials/                  # Your educational materials
├── pyproject.toml             # Project configuration
└── README.md

How It Works

1. Startup: Server indexes all documents in your materials directory
2. Connection: Claude Desktop connects via stdio transport
3. Queries: You ask educational questions in Claude
4. Tool Use: Claude calls tutor tools to search/summarize/explain
5. Response: Server returns relevant content with context
6. Answer: Claude synthesizes the information into helpful responses

Privacy & Security

• All data stays on your local machine
• No materials are sent to external services
• Claude only accesses files through the MCP protocol
• You control exactly which directory is accessible

Troubleshooting

Server not appearing in Claude Desktop

1. Check the config file syntax (valid JSON)
2. Verify Python is in your PATH
3. Check Claude Desktop logs for errors
4. Restart Claude Desktop completely

No materials found

1. Verify TUTOR_MATERIALS_PATH is an absolute path
2. Check that the directory exists and contains supported files
3. Ensure file extensions are lowercase or supported (.txt, .md, .pdf)

PDF text extraction issues

Some PDFs (especially scanned images) may not extract text properly. For best results:

• Use text-based PDFs, not scanned images
• Consider converting scanned PDFs using OCR
• Alternatively, extract text manually to .txt or .md files

License

MIT

Contributing

Contributions welcome! This is an open-source project to help students learn better with AI assistance.

Acknowledgments

Built with:

• Model Context Protocol - MCP SDK
• pypdf - PDF text extraction
• Claude - AI assistant by Anthropic