The Obsidian MCP Server transforms your Obsidian vault into an AI-accessible knowledge management and automation hub with 30+ tools across these areas:
Navigation & Search
Browse, read, and get high-level vault overviews
Full-text/title search with AND logic, date-range filtering, and tag-based lookup
Note Management
Create, edit, append, move, rename, and delete notes
Insert content under specific headings, quick-capture ideas to Inbox with timestamps
Global find & replace with dry-run preview mode
Template support and AI-assisted folder placement suggestions
Vault Analysis
Comprehensive stats, recent activity summaries, tag analysis and canonical tag registry sync
Link analysis, backlinks, local graph visualization, and orphan note detection
AI Agent / Skills System
Define custom AI personalities/roles as skill files (
.agent/skills/)Load agent instructions, enforce global vault-wide rules, generate and sync skill files
Suggest personalized skills based on vault content patterns
Semantic Search (RAG)
Meaning-based search and non-obvious connection suggestions (requires optional
[rag]install)
External Content
Extract YouTube video transcripts to enrich your knowledge base
Security & Architecture
Vault-agnostic design with intelligent auto-detection
Sensitive folder protection (
.forbidden_paths)Compatible with Claude Desktop, Cursor, Cline, and other MCP clients
Connects AI to an Obsidian vault, enabling navigation, search, note creation with templates and smart tagging, context analysis of vault structure, and agent-based operations like reorganizing notes and discovering connections between them.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Obsidian MCP Servercreate a note about quantum computing basics using the research template"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Obsidian MCP Server
An advanced MCP (Model Context Protocol) server that turns your Obsidian vault into a dynamic brain for your AI (Claude Desktop, Cursor, Claude Code, Cline, etc.). Much more than a file reader: it is an ecosystem of tools for knowledge management, workflow automation, and semantic analysis.
Features
Tool Ecosystem (30+)
The server exposes a wide variety of tools categorized by function:
Navigation: Intelligent listing, recursive reading, and advanced searching.
Creation and Editing: Automatic template usage, location suggestions, and non-destructive editing preserving metadata (frontmatter/YAML).
Analysis and Quality: Vault statistics, tag synchronization with the official registry, and integrity checks.
Graphs and Connections: Backlink analysis, orphan note detection, and local graph visualization.
Skills (Agents): Dynamic loading of AI personalities/roles from your vault (
{vault}/.agent/skills/).Semantic Search (RAG): Meaning-based searches, suggestions for non-obvious connections, and vector indexing.
YouTube: Extraction of transcripts to feed your knowledge base.
Built-in Intelligence
Vault-Agnostic Architecture: Independent of your folder structure; it uses intelligent auto-detection to find templates and resources.
Security: Strict protection of sensitive folders via
.forbidden_pathsand vault privacy configurations.Customizable Skills: Define specific AI roles directly within your vault (
.agent/skills/) for specialized tasks.
Quick Setup
Prerequisites
Python 3.11+
uv (Recommended)
Steps
Clone:
git clone https://github.com/Vasallo94/obsidian-mcp-server.git cd obsidian-mcp-serverInstall:
make install # For semantic search capabilities (RAG): pip install "obsidian-mcp-server[rag]"Configure:
cp .env.example .env # Edit .env with the absolute path to your Obsidian vault
Usage
The MCP server connects to compatible clients using the uv run obsidian-mcp-server command. Below are setup instructions for popular AI clients.
Claude Desktop Integration
Add the following to your claude_desktop_config.json:
Cursor & Cline Integration
For other clients like Cursor or Cline, you can add it as a new MCP server in their settings panel by specifying:
Type:
commandCommand:
uv run obsidian-mcp-serverEnsure the
OBSIDIAN_VAULT_PATHenvironment variable is available to the instance running the command.
Technical Documentation
To dive deeper into how the server works and how to customize it, check our detailed guides located in the docs/ folder:
Architecture: Modular structure and data flow of the project.
Tool Reference: Complete list of available MCP tools and their parameters.
Server Configuration: Guide on environment variables and technical configuration.
Agent Setup: How to organize your vault (
.agent/) with skills and contextual rules.Semantic Search (RAG): Deep dive into vector indexing and RAG mechanics.
Future Roadmap: Planned improvements and next steps for the server.
Development & Quality
Command | Description |
| Run the test suite (pytest) |
| Run static checks (Ruff + Mypy + Pylint) |
| Automatically format code |
| Run the MCP inspector for live testing |
License
This project is licensed under the MIT License.