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-mcpserver. The original README is preserved as README.upstream.md.
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
get_backlinks_fs- Find all notes linking to a specific noteget_broken_links_fs- Identify broken wikilinks in vault
analyze_note_tags_fs- Extract frontmatter and inline tagsadd_tag_fs- Add tags to note frontmatterremove_tag_fs- Remove tags from frontmattersearch_by_tag_fs- Find notes by tag
insert_after_heading_fs- Insert content after specific headingsinsert_after_block_fs- Insert after block referencesupdate_frontmatter_field_fs- Update/add frontmatter fieldsappend_to_note_fs- Append content to note end
note_statistics_fs- Comprehensive stats for individual notesvault_statistics_fs- Aggregate vault statistics
search_tasks- Search tasks with emoji metadata (π β«πβ )create_task- Create tasks with metadatatoggle_task_status- Toggle complete/incompleteupdate_task_metadata- Update due dates, priority, recurrenceget_task_statistics- Task completion analytics
extract_dataview_fields- Parse all syntax variants (::, [], ())search_by_dataview_field- Find notes by field valuesadd_dataview_field- Add inline fieldsremove_dataview_field- Remove inline fields
parse_kanban_board- Parse markdown Kanban structureadd_kanban_card- Add cards to columnsmove_kanban_card- Move cards between columnstoggle_kanban_card- Toggle card completionget_kanban_statistics- Board analytics
get_link_graph- Complete vault link graphfind_orphaned_notes- Identify isolated notesfind_hub_notes- Find highly connected notesanalyze_link_health- Vault connectivity metricsget_note_connections- Multi-level connection exploration
parse_canvas- Parse JSON Canvas v1.0 filesadd_canvas_node- Add text/file nodesadd_canvas_edge- Connect nodes with edgesremove_canvas_node- Delete nodesget_canvas_node_connections- Analyze node relationships
expand_template- Simple {{variable}} expansioncreate_note_from_template_fs- Apply templates offlinelist_templates- Browse available templates
execute_dataview_query- Execute full DQL queries (LIST/TABLE/TASK)list_notes_by_tag_dql- DQL tag-based querieslist_notes_by_folder_dql- DQL folder queriestable_query_dql- Create tabular data views
render_templater_template- Dynamic template renderingcreate_note_from_template_api- Create notes from Templater templatesinsert_templater_template- Insert templates at cursor
get_active_file- Get currently active fileopen_file- Open files in Obsidianclose_active_file- Close current filenavigate_back- Navigate backward in historynavigate_forward- Navigate forward in historytoggle_edit_mode- Switch edit/preview mode
execute_command- Run Obsidian commandslist_commands- List all available commandssearch_commands- Search commands by name/ID
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.jsonBenefits:
- β Zero local Python/uv setup required
- β Automatic dependency management
- β Isolated environment
- β Cross-platform compatibility
- β Easy updates
π Complete Docker Setup Guide
If you prefer local Python development:
# Python 3.11+ required
python --version
# Install uv (recommended package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh# 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 .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"
}
}
}
}-
Install Local REST API plugin in Obsidian
-
Configure plugin settings:
- Enable HTTPS: No (use HTTP for localhost)
- API Key: Generate a secure key
- Port: 27124 (default)
-
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"
}
}
}
}# 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"]
)# 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"
)# 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"
)# Find orphaned notes
find_orphaned_notes()
# Get link graph
get_link_graph()
# Analyze vault health
analyze_link_health()# Execute DQL query
execute_dataview_query(
query="TABLE status, due FROM #project WHERE status = 'active'"
)# 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")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
- 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
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
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=htmlobsidian-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
- Create tool module in
src/tools/ - Add Pydantic models to
src/models/obsidian.py(if needed) - Register tool in
src/server.pywith@mcp.tool()decorator - Add unit tests in
tests/unit/ - Update README.md and CHANGELOG.md
Contributions welcome! Please:
- Follow existing code style
- Add tests for new features
- Update documentation
- Ensure all tests pass
MIT License - see LICENSE for details
- Base implementation: obsidian-mcp
- MCP Protocol: Model Context Protocol
- Obsidian: Obsidian.md
- DOCKER.md - Docker deployment guide
- TESTING.md - Testing guide
- CHANGELOG.md - Version history
- README.upstream.md - Original obsidian-mcp README
- specs/ - Feature specifications and design docs