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 README.upstream.md.

🌟 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 TESTING.md 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 LICENSE for details

🙏 Acknowledgments

• Base implementation: obsidian-mcp

• MCP Protocol: Model Context Protocol

• Obsidian: Obsidian.md

📚 Additional Documentation

• TESTING.md - Testing guide

• CHANGELOG.md - Version history

• README.upstream.md - Original obsidian-mcp README

• specs/ - Feature specifications and design docs