Obsidian MCP Server

How to use

To use this MCP server, you connect your AI tool to the server via a local process that runs the Obsidian MCP backend and exposes a set of actions for note management, search, and vault organization. You will run the server in an isolated environment and provide it with your vault path. Once connected, you can read and write notes, perform fast searches, manage tags and links, and perform bulk updates. Use natural language prompts to ask the AI to find notes, create daily entries, or organize your vault, and rely on the server to execute the requested actions against your Obsidian files.

How to install

Prerequisites you need on your system are a local Obsidian vault, Python 3.10 or newer, and optionally Node.js or an MCP inspector tool for testing.

Step-by-step installation and setup are shown below. Follow the commands exactly as written to configure and run the server.

# 1) Install the MCP server runtime with the auto-configuration method:
uvx --from obsidian-mcp obsidian-mcp-configure --vault-path /path/to/your/vault

# 2) If you prefer a manual setup, you can configure Claude Desktop or Cursor IDE as described in the configuration steps below.

Additional sections

Configuration, security, troubleshooting, and practical usage notes are provided to help you get the most from the Obsidian MCP Server. The server uses a persistent index to speed up searches, supports direct file access without plugins, and aims to provide clear error messages and safe defaults for AI interactions.

Configuration and usage notes

The server is designed to be run with one-command setup, and it can be auto-configured into your Claude Desktop, Cursor IDE, or Windsurf IDE environments. It relies on a vault path you specify and ensures direct filesystem access for fast operations. You can manage notes, perform advanced searches with regex and frontmatter properties, and handle tags, links, and folder structures. Remember to restart your AI tool after updating configurations to ensure the server loads with the latest settings.

Troubleshooting

If you encounter issues, check that your vault path is correctly set and accessible, ensure you have read/write permissions to the vault folder, and confirm that the environment variable OBSIDIAN_VAULT_PATH is properly defined when starting the server. If you see a 10MB limit error for notes or 50MB for images, split large files into smaller notes or images to prevent memory issues.

Best practices for AI workflows

Always read a note before updating to avoid overwriting content unintentionally. Use append modes or section-based editing to grow notes incrementally, and rely on the server to update wiki-style links when renaming or moving notes. Maintain consistent tagging by consulting existing tags and using the available tag management tools to keep your vault well organized.

Security considerations

The MCP server accesses only the specified vault directory and validates paths to prevent directory traversal attacks. File operations are constrained to the vault, and large files are filtered to protect memory usage. Path validation helps ensure you do not accidentally expose system files.

Development and future improvements

This server leverages a modular architecture with clear tool boundaries and comprehensive error handling. It continues to optimize performance for large vaults, enhance search capabilities with persistent indexing, and improve AI-friendly tool definitions and error messages.

read_note

Read the content and metadata of a specific note.

create_note

Create a new note or update an existing one with optional overwrite behavior.

update_note

Update the content of an existing note with optional merge strategies.

edit_note_section

Edit a specific section identified by a markdown heading within a note.

delete_note

Delete a note from the vault.

search_notes

Search notes by text or tags with context and result limits.

search_by_date

Search notes by creation or modification date with flexible ranges.

search_by_regex

Find notes using regular expressions for advanced pattern matching.

search_by_property

Search notes by frontmatter properties with operators and context.

list_notes

List notes in a directory with optional recursive traversal.

list_folders

List folders in the vault with optional recursive traversal.

create_folder

Create a new folder hierarchy including parent folders.

move_note

Move a note to a new location, with optional link updates.

rename_note

Rename a note and update all references across the vault.

move_folder

Move an entire folder and its contents.

add_tags

Add tags to a note's frontmatter, including hierarchical tags.

update_tags

Update or merge tags on a note, with optional inline body removal.

remove_tags

Remove specified tags from a note.

batch_update_properties

Bulk update frontmatter properties across multiple notes.

get_note_info

Get metadata and statistics about a note without content.

read_image

View and resize an image from the vault for display.

view_note_images

Extract and view all images embedded in a note.

list_tags

List unique tags with usage statistics and optional file lists.

find_orphaned_notes

Identify notes lacking backlinks, links, tags, metadata, or being isolated.

get_backlinks

Find all notes that link to a specific note.

get_outgoing_links

List all links from a specific note.

find_broken_links

Identify broken links across the vault, a directory, or a single note.