Obsidian MCP

Search, read and edit the notes in your Obsidian vault.

Started in our test
★ 4.5K GitHub stars
5K downloads a week
Last commit 31 Aug 2026

At a glance

This server reaches your vault through the Local REST API community plugin, so Obsidian has to be open while you use it. The model can list folders, search across every note, read files, append text, and insert text under a particular heading, block or frontmatter field without rewriting the whole note.

It can also delete files and folders. Keep the vault synced or backed up, and tell the assistant to use Obsidian at the start of a chat, because the author notes it then reaches for the tools reliably.

Made by: Markus Pfundstein, an independent developer
Latest version: 0.2.3 (20 Aug 2026)
PyPI package: mcp-obsidian
GitHub stars: 4.5K
Downloads: 5K a week
Last commit: 31 Aug 2026
Tools: 15
Runs on: Your computer

Our check: We ran this exact config on 27 Oct 2026: it started and answered with 15 tools. The shared database gave "npx mcp-obsidian", an npm package by someone else. This project publishes mcp-obsidian on PyPI and runs with uvx.

What's in the pod: its tools

We found 15 tools when we started it on 27 Oct 2026. 0 only read. The rest can change things, so keep your app's "ask before each tool call" setting on for them.

Changes things15 tools · Can create, edit, send or delete.

Tool	What it is for
`obsidian_append_content`	Adds text to the end of a note, creating it if it does not exist.
`obsidian_batch_get_file_contents`	Reads several notes in one call, each under its own header.
`obsidian_complex_search`	Searches with a JsonLogic query, including glob and regular-expression matches on paths and content.
`obsidian_delete_file`	Deletes a note or a folder.
`obsidian_get_file_contents`	Reads one note in full.
`obsidian_get_frontmatter`	Returns only a note's YAML frontmatter, which is lighter when you just need tags or dates.
`obsidian_get_periodic_note`	Opens the current daily, weekly, monthly, quarterly or yearly note.
`obsidian_get_recent_changes`	Lists the notes changed most recently.
`obsidian_get_recent_periodic_notes`	Lists the most recent periodic notes of one type.
`obsidian_list_files_in_dir`	Lists the files and folders inside one folder.
`obsidian_list_files_in_vault`	Lists the files and folders at the top of the vault.
`obsidian_patch_content`	Inserts or replaces text under a heading, at a block reference or in a frontmatter field.
`obsidian_put_content`	Creates a note or replaces a whole note's text. The old text is gone.
`obsidian_search_by_tag`	Finds every note with a tag, from frontmatter or inline #tags.
`obsidian_simple_search`	Finds notes that contain a piece of text, with the surrounding context.

Grouped and described by us. The README on GitHub lists the inputs each tool takes.

How clearly it describes its tools to your assistant

Tools with a description: 15 of 15
Say if they change things: 0 of 15
Context it takes, at least: ~1,200 tokens

No tool says whether it only reads or can change things, so your client treats them all alike: keep approvals on.

From the tool list it sent us. The token figure counts names, descriptions and input names; the full schemas your client loads add more.

Set it up

In Obsidian, open Settings → Community plugins, install Local REST API and enable it.
Copy the API key from the plugin's settings into OBSIDIAN_API_KEY.
Keep Obsidian open while you use the server.

Pick your app for the exact snippet and where it goes.

Where it goes: claude_desktop_config.json (Settings → Developer → Edit Config)

Claude Desktop

{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": [
        "mcp-obsidian"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "YOUR_LOCAL_REST_API_KEY",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

Where it goes: Your terminal, in the project folder

Claude Code

claude mcp add-json obsidian '{"command":"uvx","args":["mcp-obsidian"],"env":{"OBSIDIAN_API_KEY":"YOUR_LOCAL_REST_API_KEY","OBSIDIAN_HOST":"127.0.0.1","OBSIDIAN_PORT":"27124"}}'

Where it goes: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

Cursor

{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": [
        "mcp-obsidian"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "YOUR_LOCAL_REST_API_KEY",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

Where it goes: .vscode/mcp.json in your project

VS Code

{
  "servers": {
    "obsidian": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-obsidian"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "YOUR_LOCAL_REST_API_KEY",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

Where it goes: ~/.codeium/windsurf/mcp_config.json

Windsurf

{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": [
        "mcp-obsidian"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "YOUR_LOCAL_REST_API_KEY",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

New to this? See the setup guides for Claude Code, Cursor, Claude Desktop and ChatGPT.

Settings

Names are exactly as the project spells them. Required ones are marked.

Setting	What it does
`OBSIDIAN_API_KEY`Environment variable · required	The key shown in the Local REST API plugin's settings.
`OBSIDIAN_HOST`Environment variable	Where Obsidian is running. Defaults to 127.0.0.1; use host.docker.internal when the server runs in Docker.`127.0.0.1`
`OBSIDIAN_PORT`Environment variable	The plugin's HTTPS port. Defaults to 27124.`27124`

What it can touch

It can read

Every note and folder in the vault Obsidian has open

It can change

Notes it appends to, patches or overwrites
Notes and folders it deletes

Safer setup: Keep the vault under sync or version control so changes can be undone, and ask the model to append or patch rather than overwrite.

Before you start

Obsidian with the Local REST API community plugin enabled
The API key from that plugin
uv (Python 3.11 or newer)

If it does not work

Every call fails to connect: Obsidian must be open with the Local REST API plugin enabled. Check the port in the plugin's settings matches OBSIDIAN_PORT.
Claude Desktop cannot find uvx: Run which uvx and put the full path in the command field.
The model answers from memory instead of the vault: Say at the start of the chat that it should use Obsidian; after that it calls the tools reliably.
It fails to start after installing other Python packages: It needs version 1 of the MCP Python library. uvx keeps its own environment, so start it with uvx rather than pip.

Peas in a pod: similar servers

How Obsidian MCP lines up against other knowledge and work apps servers on the shelf.

Server	Tools	Runs on	Licence	Stars
Obsidian MCP	15	Your computer	–	4.5K
Google Workspace MCP	43	Your computer	MIT	3.4K
12306 MCP	8	Your computer	MIT	2.4K
Notion	24	Your computer or hosted	MIT	4.7K
MCP Atlassian (Jira and Confluence)	98	Your computer	–	6K