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