Obsidian MCP Tool Server

You run an MCP server that exposes tools to interact with an Obsidian vault. It lets you read and write notes, manage metadata, navigate your vault, and gather analytics like daily notes, links, and tags, all from connected clients such as AI assistants or editors.

How to use

Start the server locally so an MCP client can connect to it. You configure a local Python process that runs the server script, then point your MCP client to that local process. Once running, you can perform common vault actions from the client: read and write notes, edit note metadata, list folders and notes, perform content and metadata searches, manage daily notes, and retrieve outgoing links, backlinks, and tags.

How to install

Prerequisites: Python and optional tooling for virtual environments.

Clone the project and enter the directory where the server resides.

Create a Python virtual environment to isolate dependencies.

Activate the virtual environment.

Install the package and dependencies from the local source.

Run the server manually to test locally before wiring it into a client.

Configuration and usage notes

Configure environment variables in a .env file at the project root to control how the MCP server runs. The only required variable is the path to your Obsidian vault.

Set the vault path to an absolute path using forward slashes, even on Windows. You can also place settings in your system environment if you prefer.

Running Manually (for Testing/Debugging)

Activate your virtual environment and run the server script directly to observe startup messages and errors.

(.venv) ...> python obsidian_mcp_server/main.py

Client Configuration (Example: Claude Desktop)

Configure a client to launch the MCP server as a local (stdio) endpoint. Use absolute paths and an explicit Python executable inside your virtual environment.

The client configuration must point to the Python executable in your venv and the server main script, and it should provide the vault path via environment variables.

Available MCP Tools

list_folders, list_notes, get_note_content, get_note_metadata, get_outgoing_links, get_backlinks, get_all_tags, search_notes_content, search_notes_metadata, search_folders, create_note, edit_note, append_to_note, update_note_metadata, delete_note, get_daily_note_path, create_daily_note, append_to_daily_note.

Configuration example for local stdio server

If you run the server locally via a Python environment, you can configure a stdio MCP entry like this.

{
  "type": "stdio",
  "name": "obsidian",
  "command": "python",
  "args": ["obsidian_mcp_server/main.py"],
  "env": {
    "OMCP_VAULT_PATH": "C:/path/to/your/Obsidian/Vault",
    "OMCP_DAILY_NOTE_LOCATION": "Journal/Daily"
  }
}

Roadmap

Future work includes template-based note creation, folder creation utilities, and richer vault querying and integration features.

Troubleshooting and notes

If the server cannot start, check that the vault path exists and is readable, the virtual environment is activated, and the Python process has permission to access files. Run the server directly from a terminal to surface Python errors, such as ImportError or FileNotFoundError.

Ensure client JSON configurations use valid syntax with properly escaped Windows paths, and avoid comments in JSON. Restart the client after changes to its configuration.

Available tools

list_folders

List folders in the vault to help you understand vault structure.

list_notes

List notes in a specified folder or vault section.

get_note_content

Retrieve the full content of a note by path or identifier.

get_note_metadata

Fetch metadata (frontmatter) for a given note.

get_outgoing_links

Return links that this note points to.

get_backlinks

Return notes that link to this note.

get_all_tags

Collect all tags used across notes in the vault.

search_notes_content

Search notes by content with optional filters.

search_notes_metadata

Search notes by metadata fields such as tags or frontmatter keys.

search_folders

Find folders by name or characteristics.

create_note

Create a new note with given content and metadata.

edit_note

Edit the content of an existing note.

append_to_note

Append content to an existing note.

update_note_metadata

Update the metadata/frontmatter of a note.

delete_note

Delete a note from the vault.

get_daily_note_path

Get the path to the daily note for a given date.

create_daily_note

Create a daily note at the configured location.

append_to_daily_note

Append content to the daily note.