obsidian-mcp

aleksakarac/obsidian-mcp

3.3

If you are the rightful owner of obsidian-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Obsidian MCP Extended is an advanced version of the obsidian-mcp server, offering enhanced features for managing notes with improved performance and functionality.

Tools
12
Resources
0
Prompts
0

Obsidian MCP Extended

A comprehensive MCP server for Obsidian with 45 tools across hybrid filesystem-native and API-based architectures. Extends obsidian-mcp with advanced plugin control, backlinks, tag management, and analytics.

Note: This project extends the base obsidian-mcp server. The original README is preserved as .

🌟 Features

Hybrid Architecture

Filesystem-Native Tools (33 tools) - Work completely offline, no Obsidian required:

  • ✅ Direct file access for maximum performance
  • ✅ Zero Obsidian plugins needed
  • ✅ Instant startup, minimal memory
  • ✅ Full offline capability

API-Based Tools (12 tools) - Enhanced features when Obsidian is running:

  • 🔌 Real-time workspace control
  • 🔌 Advanced plugin integration (Templater, Dataview DQL)
  • 🔌 Command palette access
  • 🔌 Requires Local REST API plugin

📦 Complete Tool List (45 Tools)

🔗 Backlink Analysis (2 tools - Filesystem)

  • get_backlinks_fs - Find all notes linking to a specific note
  • get_broken_links_fs - Identify broken wikilinks in vault

🏷️ Tag Management (4 tools - Filesystem)

  • analyze_note_tags_fs - Extract frontmatter and inline tags
  • add_tag_fs - Add tags to note frontmatter
  • remove_tag_fs - Remove tags from frontmatter
  • search_by_tag_fs - Find notes by tag

✏️ Smart Content Insertion (4 tools - Filesystem)

  • insert_after_heading_fs - Insert content after specific headings
  • insert_after_block_fs - Insert after block references
  • update_frontmatter_field_fs - Update/add frontmatter fields
  • append_to_note_fs - Append content to note end

📊 Statistics & Analytics (2 tools - Filesystem)

  • note_statistics_fs - Comprehensive stats for individual notes
  • vault_statistics_fs - Aggregate vault statistics

✅ Tasks Plugin (5 tools - Filesystem)

  • search_tasks - Search tasks with emoji metadata (📅⏫🔁✅)
  • create_task - Create tasks with metadata
  • toggle_task_status - Toggle complete/incomplete
  • update_task_metadata - Update due dates, priority, recurrence
  • get_task_statistics - Task completion analytics

📊 Dataview Inline Fields (4 tools - Filesystem)

  • extract_dataview_fields - Parse all syntax variants (::, [], ())
  • search_by_dataview_field - Find notes by field values
  • add_dataview_field - Add inline fields
  • remove_dataview_field - Remove inline fields

📋 Kanban Boards (5 tools - Filesystem)

  • parse_kanban_board - Parse markdown Kanban structure
  • add_kanban_card - Add cards to columns
  • move_kanban_card - Move cards between columns
  • toggle_kanban_card - Toggle card completion
  • get_kanban_statistics - Board analytics

🔗 Enhanced Link Tracking (5 tools - Filesystem)

  • get_link_graph - Complete vault link graph
  • find_orphaned_notes - Identify isolated notes
  • find_hub_notes - Find highly connected notes
  • analyze_link_health - Vault connectivity metrics
  • get_note_connections - Multi-level connection exploration

🎨 Canvas Files (5 tools - Filesystem)

  • parse_canvas - Parse JSON Canvas v1.0 files
  • add_canvas_node - Add text/file nodes
  • add_canvas_edge - Connect nodes with edges
  • remove_canvas_node - Delete nodes
  • get_canvas_node_connections - Analyze node relationships

📝 Templates (3 tools - Filesystem)

  • expand_template - Simple {{variable}} expansion
  • create_note_from_template_fs - Apply templates offline
  • list_templates - Browse available templates

🔌 Dataview Query API (4 tools - Requires Obsidian + Dataview)

  • execute_dataview_query - Execute full DQL queries (LIST/TABLE/TASK)
  • list_notes_by_tag_dql - DQL tag-based queries
  • list_notes_by_folder_dql - DQL folder queries
  • table_query_dql - Create tabular data views

🔌 Templater Plugin API (3 tools - Requires Obsidian + Templater)

  • render_templater_template - Dynamic template rendering
  • create_note_from_template_api - Create notes from Templater templates
  • insert_templater_template - Insert templates at cursor

🔌 Workspace Management (6 tools - Requires Obsidian)

  • get_active_file - Get currently active file
  • open_file - Open files in Obsidian
  • close_active_file - Close current file
  • navigate_back - Navigate backward in history
  • navigate_forward - Navigate forward in history
  • toggle_edit_mode - Switch edit/preview mode

🔌 Command Execution (3 tools - Requires Obsidian)

  • execute_command - Run Obsidian commands
  • list_commands - List all available commands
  • search_commands - Search commands by name/ID

🚀 Quick Start

Prerequisites

# Python 3.11+ required
python --version

# Install uv (recommended package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

Installation

# Clone repository
git clone https://github.com/aleksakarac/obsidian-mcp.git
cd obsidian-mcp

# Install with uv (recommended)
uv pip install .

# Or with pip
pip install .

Configuration

For Filesystem-Only Tools (No Obsidian Required)

Add to your Claude Code config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/obsidian-mcp",
        "run",
        "obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}
For Full Hybrid Mode (Filesystem + API Tools)

  1. Install Local REST API plugin in Obsidian

  2. Configure plugin settings:

    • Enable HTTPS: No (use HTTP for localhost)
    • API Key: Generate a secure key
    • Port: 27124 (default)

  3. Update Claude Code config:

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/obsidian-mcp",
        "run",
        "obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault",
        "OBSIDIAN_REST_API_KEY": "your-api-key-here",
        "OBSIDIAN_API_URL": "http://localhost:27124"
      }
    }
  }
}

📖 Usage Examples

Tasks Plugin (Filesystem-Native)

# Search for high-priority incomplete tasks
search_tasks(
    status="incomplete",
    priority="high",
    sort_by="due_date",
    limit=10
)

# Create task with metadata
create_task(
    file_path="Projects/Current.md",
    content="Review PR #123",
    priority="high",
    due_date="2025-11-01",
    tags=["code-review", "urgent"]
)

Dataview Fields (Filesystem-Native)

# Extract all inline fields
extract_dataview_fields(file_path="Project Notes.md")

# Find notes where status=active
search_by_dataview_field(
    field_name="status",
    field_value="active"
)

Kanban Boards (Filesystem-Native)

# Parse board structure
parse_kanban_board(file_path="Boards/Sprint.md")

# Move card between columns
move_kanban_card(
    file_path="Boards/Sprint.md",
    card_text="Implement authentication",
    from_column="To Do",
    to_column="In Progress"
)

Link Analysis (Filesystem-Native)

# Find orphaned notes
find_orphaned_notes()

# Get link graph
get_link_graph()

# Analyze vault health
analyze_link_health()

Dataview Queries (Requires Obsidian)

# Execute DQL query
execute_dataview_query(
    query="TABLE status, due FROM #project WHERE status = 'active'"
)

Workspace Control (Requires Obsidian)

# Open file
open_file(file_path="Daily/2025-10-22.md")

# Get active file
get_active_file()

# Execute command
execute_command(command_id="editor:toggle-bold")

🏗️ Architecture

Hybrid Design Philosophy

Filesystem-First Approach:

  • Everything that CAN be filesystem-native, IS filesystem-native
  • Direct file access for reading/writing markdown
  • Zero dependencies on Obsidian plugins for core features
  • Full offline capability

API Enhancement:

  • API tools complement filesystem tools
  • Provide features impossible without Obsidian (workspace UI, command execution)
  • Enable plugin integration (Templater, Dataview DQL)
  • Graceful degradation with clear error messages

Technology Stack

  • FastMCP: MCP protocol implementation
  • Pydantic: Type-safe data models with validation
  • Python Standard Library: Zero external dependencies for filesystem operations
  • httpx: Async HTTP client for API tools

Performance

Filesystem Tools:

  • 1,000 notes: < 3 seconds for full vault scans
  • Single note operations: < 100ms
  • Link graph generation: < 10 seconds for 1,000 notes

API Tools:

  • Command execution: < 500ms
  • Query execution: Depends on Dataview plugin
  • Workspace operations: < 200ms

🧪 Testing

See for comprehensive testing documentation.

# Run all tests
uv run pytest

# Run specific test suite
uv run pytest tests/unit/test_tasks.py -v

# Run with coverage
uv run pytest --cov=src --cov-report=html

📝 Development

Project Structure

obsidian-mcp/
├── src/
│   ├── models/          # Pydantic data models
│   ├── tools/           # MCP tool implementations
│   ├── utils/           # Shared utilities (patterns, API client)
│   └── server.py        # FastMCP server with tool registrations
├── tests/
│   ├── unit/            # Unit tests for tools
│   └── integration/     # End-to-end workflow tests
├── specs/               # Feature specifications
└── pyproject.toml       # Project configuration

Adding New Tools

  1. Create tool module in src/tools/
  2. Add Pydantic models to src/models/obsidian.py (if needed)
  3. Register tool in src/server.py with @mcp.tool() decorator
  4. Add unit tests in tests/unit/
  5. Update README.md and CHANGELOG.md

🤝 Contributing

Contributions welcome! Please:

  1. Follow existing code style
  2. Add tests for new features
  3. Update documentation
  4. Ensure all tests pass

📄 License

MIT License - see for details

🙏 Acknowledgments

📚 Additional Documentation

  • - Testing guide
  • - Version history
  • - Original obsidian-mcp README
  • - Feature specifications and design docs