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

Related MCP server: Recalla

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