Obsidian Learning Extension MCP Server

A Model Context Protocol (MCP) server that extends the official Obsidian MCP server with intelligent learning and second-brain features.

Features

🎯 Challenge System

• AI-Generated Challenges: Create personalized learning challenges based on topic, difficulty, and type
• Progress Tracking: Monitor time spent and status for each challenge
• Challenge Types: Knowledge, Practical, Teaching, Analysis, Creative
• Difficulty Levels: Beginner, Intermediate, Advanced, Expert

📊 Progress Analytics

• Activity Recording: Track learning sessions with duration and mastery ratings
• Statistics Dashboard: View time spent, average mastery, and activity trends
• Topic Analysis: See time distribution across different topics
• Performance Insights: Identify areas for improvement

🔄 Spaced Repetition

• Smart Scheduling: Automatically schedule reviews based on spaced repetition algorithm
• Performance-Based Intervals: Review intervals adjust based on how well you remember
• Due Review Tracking: Get notifications for overdue reviews
• Note Integration: Link reviews directly to Obsidian notes

🧠 Knowledge Gap Analysis

• Identify Weak Areas: Find topics with low mastery scores
• Activity Tracking: See which topics haven't been practiced recently
• Personalized Suggestions: Get AI-powered recommendations for what to study next
• Focus Analysis: Analyze specific areas or your entire knowledge base

Prerequisites

• Docker and Docker Compose
• Official Obsidian MCP server (from Docker) already set up
• Claude Desktop configured with Obsidian MCP

Installation

1. Clone the Repository

git clone https://github.com/yourusername/obsidian-learning-extension.git
cd obsidian-learning-extension

2. Build the Docker Image

docker-compose build

3. Test the Server

docker-compose up

The server should start and wait for stdio communication.

Configuration

Add to Claude Desktop Config

Edit your Claude Desktop configuration file:

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

Add the learning extension server alongside your existing Obsidian server:

{
  "mcpServers": {
    "obsidian": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OBSIDIAN_HOST",
        "-e", "OBSIDIAN_API_KEY",
        "mcp/obsidian"
      ],
      "env": {
        "OBSIDIAN_HOST": "host.docker.internal",
        "OBSIDIAN_API_KEY": "YOUR_API_KEY"
      }
    },
    "obsidian-learning": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/ABSOLUTE/PATH/TO/obsidian-learning-extension/data:/data:rw",
        "obsidian-learning-extension:latest"
      ]
    }
  }
}

Important: Replace /ABSOLUTE/PATH/TO/obsidian-learning-extension with your actual path!

Restart Claude Desktop

Completely quit and reopen Claude Desktop to load the new server.

Available Tools

Challenge Management

create_challenge

Create a new learning challenge with AI-generated content.

Parameters:

• topic (string): Topic to learn (e.g., "Docker Networking")
• difficulty (enum): beginner, intermediate, advanced, expert
• challenge_type (enum): knowledge, practical, teaching, analysis, creative
• description (string, optional): Custom challenge description

Example:

"Create an intermediate practical challenge on Docker networking"

list_challenges

List all challenges with optional filtering.

Parameters:

• status (enum, optional): pending, in_progress, completed, archived
• difficulty (enum, optional): Filter by difficulty level

Example:

"Show me all my in-progress challenges"

get_challenge

Get detailed information about a specific challenge.

Parameters:

• challenge_id (string): ID of the challenge

update_challenge_status

Update challenge status and add notes.

Parameters:

• challenge_id (string): Challenge ID
• status (enum): pending, in_progress, completed, archived
• notes (string, optional): Notes about the status change

Example:

"Mark challenge ch_abc123 as completed with notes: Built a working multi-container app"

Progress Tracking

record_progress

Record a learning session.

Parameters:

• topic (string): What you studied
• activity (string): What you did
• duration_minutes (number): Time spent
• mastery_rating (number): Self-assessment 0-10
• challenge_id (string, optional): Link to a challenge
• notes (string, optional): Additional notes

Example:

"Record 45 minutes learning Docker volumes, mastery 7/10, completed tutorial"

get_progress_stats

View learning statistics and analytics.

Parameters:

• topic (string, optional): Filter by topic
• days (number, optional): Days to look back (default: 30)

Example:

"Show my learning stats for the last 7 days"

Spaced Repetition

schedule_review

Schedule a review for spaced repetition.

Parameters:

• topic (string): Topic to review
• note_path (string): Path to note in Obsidian
• initial_interval_days (number, optional): First review interval

Example:

"Schedule a review for Docker networking, note at Software Development/Docker Networking.md"

get_due_reviews

Get all reviews that are due or overdue.

Example:

"What reviews are due today?"

complete_review

Mark a review as completed and schedule the next one.

Parameters:

• review_id (string): Review ID
• performance (enum): weak, moderate, strong, perfect
• notes (string, optional): Review notes

Example:

"Complete review rv_abc123 with strong performance"

Knowledge Analysis

suggest_next_topic

Get AI suggestions for what to study next.

Parameters:

• area (string, optional): Focus area (e.g., "Docker")

Example:

"What should I study next?"

analyze_knowledge_gaps

Analyze your learning to find gaps and weak areas.

Parameters:

• focus_area (string, optional): Area to analyze

Example:

"Analyze my knowledge gaps in programming"

Usage Examples

Getting Started

Claude: "Create a beginner knowledge challenge on Python async/await"
Claude: "List all my pending challenges"
Claude: "Update challenge ch_abc123 to in_progress"

During Learning

Claude: "Record 30 minutes studying async programming, mastery 6/10"
Claude: "What are my learning stats this week?"

Maintaining Knowledge

Claude: "Schedule a review for async programming at Python/Async.md"
Claude: "What reviews are due?"
Claude: "Complete review rv_xyz789 with strong performance"

Getting Insights

Claude: "What should I study next?"
Claude: "Analyze my knowledge gaps"
Claude: "Show challenges with low mastery scores"

Data Storage

All data is stored in JSON files in the data/ directory:

• challenges.json: Challenge definitions and status
• progress.json: Learning activity log
• reviews.json: Spaced repetition schedule

These files are automatically created and maintained by the server.

Architecture

┌─────────────────┐
│  Claude Desktop │
└────────┬────────┘
         │
    ┌────┴─────────────────┐
    │                      │
┌───▼────────┐    ┌───────▼────────┐
│ Official   │    │   Learning     │
│ Obsidian   │    │   Extension    │
│ MCP Server │    │   MCP Server   │
└───┬────────┘    └────────┬───────┘
    │                      │
┌───▼────────────┐    ┌────▼──────┐
│ Obsidian Vault │    │   JSON    │
│  (via REST)    │    │   Data    │
└────────────────┘    └───────────┘

Both servers work together:

• Official server: Handles all Obsidian file operations
• Learning extension: Provides intelligent learning features

Development

Running Locally

# Install dependencies
pip install -r requirements.txt

# Run server
python learning_server.py

Building Docker Image

docker-compose build

Viewing Logs

# With docker-compose
docker-compose logs -f

# With docker
docker logs obsidian-learning -f

Debugging

Use the MCP Inspector for debugging:

npx @modelcontextprotocol/inspector python learning_server.py

Troubleshooting

Server Won't Start

• Check Docker is running: docker ps
• Rebuild image: docker-compose build --no-cache
• Check logs: docker-compose logs

Tools Not Showing in Claude

• Verify Claude Desktop config JSON is valid
• Ensure data directory path is absolute (not relative)
• Restart Claude Desktop completely
• Check Claude logs: ~/Library/Logs/Claude/ (macOS)

Data Not Persisting

• Verify volume mount in docker-compose.yml
• Check data directory permissions
• Ensure path is absolute

Permission Errors

# Fix data directory permissions
chmod 755 data/

Roadmap

Phase 2 (Planned)

• [ ] Knowledge graph visualization
• [ ] Automatic note linking based on topics
• [ ] Learning streak tracking
• [ ] Challenge templates library
• [ ] Export progress reports

Phase 3 (Future)

• [ ] Machine learning for personalized difficulty adjustment
• [ ] Collaborative challenges
• [ ] Integration with external learning platforms
• [ ] Mobile notifications for reviews
• [ ] Advanced analytics dashboard

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - feel free to use and modify!

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

• Built on the Model Context Protocol
• Complements the Official Obsidian MCP Server
• Inspired by spaced repetition research and second brain methodology