8000 GitHub - jfbeaulieu-nm/obsidian-mcp: Enhanced Obsidian MCP server with hybrid plugin control - filesystem-native and API-based tools for Tasks, Dataview, Kanban, Canvas, and more Β· GitHub
[go: up one dir, main page]

Skip to content

About

Enhanced Obsidian MCP server with hybrid plugin control - filesystem-native and API-based tools for Tasks, Dataview, Kanban, Canvas, and more

Resources

Stars

0 stars

Watchers

0 watching

Forks

Β 
Β 

Latest commit

Β 

History

20 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

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

🐳 Recommended: Docker Deployment (Easiest)

For the easiest setup with automatic dependency management and isolation:

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

# Build Docker image
./build.sh  # Linux/Mac
# or
build.bat   # Windows

# Configure MCP client (see DOCKER.md for details)
# Add to ~/.config/claude/claude_desktop_config.json or .roo/mcp.json

Benefits:

  • βœ… Zero local Python/uv setup required
  • βœ… Automatic dependency management
  • βœ… Isolated environment
  • βœ… Cross-platform compatibility
  • βœ… Easy updates

πŸ“– Complete Docker Setup Guide


🐍 Alternative: Local Python Setup

If you prefer local Python development:

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


πŸ“š Additional Documentation

About

Enhanced Obsidian MCP server with hybrid plugin control - filesystem-native and API-based tools for Tasks, Dataview, Kanban, Canvas, and more

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0