obsidian-mcp
Provides read-only access to an Obsidian vault, enabling file listing, content reading, file search by name, and full-text search across notes.
Click on "Deploy 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 search for all mentions of 'TODO' in my vault"
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 MCP (Model Context Protocol) server that provides access to your Obsidian vault, enabling seamless interaction with your notes, documents, and knowledge base.
Features
File Discovery: List all files in your Obsidian vault
Content Reading: Read the full content of any file in your vault
File Search: Find files by name or path patterns
Content Search: Search for text within all files in your vault
Safe Access: Excludes system directories like
.obsidianand.gitLarge File Handling: Automatically handles large files with size limits and content truncation
Related MCP server: obsidian-mcp
Tools Available
list_files()- Get a list of all files in your vaultget_file_content(file_path)- Read the content of a specific filefind_files(query)- Find files by name matching a queryfind_in_all_file_content(query)- Search for text within all file contents
Installation
Clone this repository:
git clone <repository-url> cd obsidian-mcpInstall dependencies using uv (recommended) or pip:
# Using uv uv sync # Or using pip pip install -e .
Configuration for Claude Desktop
To use this MCP server with Claude Desktop, you need to add it to your Claude Desktop configuration file.
Windows Configuration
Open your Claude Desktop configuration file at:
%APPDATA%\Claude\claude_desktop_config.jsonAdd the following configuration to the
mcpServerssection:{ "mcpServers": { "obsidian-mcp": { "command": "uv", "args": [ "run", "python", "C:\\path\\to\\your\\obsidian-mcp\\main.py", "C:\\path\\to\\your\\obsidian\\vault" ] } } }
macOS/Linux Configuration
Open your Claude Desktop configuration file at:
~/Library/Application Support/Claude/claude_desktop_config.json # macOS ~/.config/claude/claude_desktop_config.json # LinuxAdd the following configuration to the
mcpServerssection:{ "mcpServers": { "obsidian-mcp": { "command": "uv", "args": [ "run", "python", "/path/to/your/obsidian-mcp/main.py", "/path/to/your/obsidian/vault" ] } } }
Alternative Configuration (without uv)
If you prefer not to use uv, you can configure it to run directly with Python:
{
"mcpServers": {
"obsidian-mcp": {
"command": "python",
"args": [
"/path/to/your/obsidian-mcp/main.py",
"/path/to/your/obsidian/vault"
]
}
}
}Important Notes
Replace
/path/to/your/obsidian-mcp/main.pywith the actual path to the main.py fileReplace
/path/to/your/obsidian/vaultwith the actual path to your Obsidian vault directoryUse forward slashes (/) in paths even on Windows when using the JSON configuration
Restart Claude Desktop after making configuration changes
Usage
Once configured, you can ask Claude to:
"List all files in my Obsidian vault"
"Show me the content of my daily note from yesterday"
"Find all files related to 'project alpha'"
"Search for all mentions of 'TODO' in my vault"
"What notes do I have about machine learning?"
Claude will use the MCP server to access your vault and provide responses based on your actual notes and documents.
Security
This MCP server provides read-only access to your Obsidian vault. It cannot create, modify, or delete files. It automatically excludes system directories like .obsidian and .git from access.
Development
Language: Python 3.11+
Framework: FastMCP
Dependencies: See
pyproject.toml
Development Setup
Install development dependencies:
uv sync --group devRun linting:
uv run ruff check uv run ruff format
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Available Tools
4 toolsfind_filesA
Find files in the Obsidian Vault that match a query and return the file paths.
Args:
query: Search term to match against file names (case-insensitive).
Can be a partial filename, extension, or keyword.
Examples: 'meeting', '.md', 'project-alpha'
Returns:
List of relative file paths that match the query.
Use these paths with get_file_content() to read the files.
Returns message if no matches found.
Note: Searches only file names/paths, not file contents. Use find_in_all_file_content()
to search within file contents.
Inputs: query (required). Returns: result
find_in_all_file_contentA
Find a query in the content of all files in the Obsidian Vault and return the file paths.
Args:
query: Text to search for within file contents (case-insensitive).
Can be words, phrases, or partial text.
Examples: 'meeting notes', 'project deadline', 'TODO'
Returns:
Newline-separated list of file paths that contain the query text.
Only returns the file paths, not the matching content excerpts.
Use get_file_content() on returned paths to read the full files.
Returns message if no matches found.
Note: Searches the full text content of all readable files. Skips binary files.
For filename searches, use find_files() instead.
Inputs: query (required). Returns: result
get_file_contentA
Get the content of a file in the Obsidian Vault.
Args:
file_path: The relative file path from the vault root. Use the exact path
format returned by list_files() or find_files().
Examples: 'notes/meeting-notes.md', 'daily/2024-01-15.md'
This parameter is REQUIRED - you must specify which file to read.
Returns:
The full text content of the file, or an error message if the file
cannot be read or doesn't exist.
Note: Only reads text files. Binary files will return an encoding error.
Inputs: file_path (required). Returns: object
list_filesA
List all files in the Obsidian Vault and return their paths.
Returns a newline-separated list of file paths relative to the vault root.
Use these exact paths with get_file_content() to read file contents.
Excludes system directories like .obsidian.
Example return format:
notes/meeting-notes.md
projects/project-alpha.md
daily/2024-01-15.md
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Most tools are clearly distinct: list_files lists all files, find_files searches by filename, find_in_all_file_content searches content, and get_file_content reads a specific file. The only potential confusion is between list_files and find_files, but their descriptions clarify the difference.
All tool names use snake_case and follow a verb_noun pattern (list_files, get_file_content, find_files). One name, find_in_all_file_content, is more verbose but still consistent in style.
Four tools is a reasonable count for a read-only Obsidian Vault server. The scope is narrow but sufficient for listing, retrieving, and searching files.
The tool set covers the common read operations for a Vault: listing files, reading content, and searching by name or content. Missing write operations like create/update/delete, but for a read-only server the surface is functional.
Maintenance
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Related MCP Servers
- AlicenseAqualityAmaintenanceStandalone MCP server for Obsidian vaults - hybrid search (FTS5 + vector + cross-encoder reranking), images and PDFs in agent-readable form, Kanban-aware tasks (Tasks-plugin + Dataview formats), structured memory with topic recall, fine-grained read/write tools for optimal token efficiency, and link graph support. Run locally, self-host, or one-click deploy for remote access. OAuth 2.1.1633636 npm38MIT
- AlicenseAqualityBmaintenanceEnables MCP clients to safely read, search, create, edit, delete, and move notes in an Obsidian vault, with automatic link repair and reversible deletes.10MIT
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to search, read, list, and append to markdown notes in a local Obsidian vault or folder of .md files.-
- AlicenseNot gradedqualityBmaintenanceEnables LLM clients to read, search, and write to a local Obsidian vault over MCP, with full-text search, vault analytics, health scoring, and policy-enforced file operations.1MIT