# obsidian-mcp-server [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/cyanheads/obsidian-mcp-server  
**GitHub Stars:** 700  
**npm Downloads (last month):** 24610  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/obsidian-mcp-server

## Description
MCP server for Obsidian vaults — read, write, search, and edit notes via the Local REST API plugin.

## Tools
Capabilities this server exposes over MCP:

- **obsidian_get_note** — Read a note as raw content, full structured form, document map, or a single section
- **obsidian_list_notes** — List notes and folders under a vault path, recursively, with extension and name filters
- **obsidian_list_tags** — List vault tags with usage counts, most-used first
- **obsidian_search_notes** — Search by text, JSONLogic, or BM25-ranked Omnisearch when that plugin is reachable
- **obsidian_write_note** — Create a note, replace one section, or overwrite a whole file with `overwrite: true
- **obsidian_append_to_note** — Append to a note (creating it if missing) or to one heading, block, or frontmatter field
- **obsidian_patch_note** — Append, prepend, or replace against one heading, block reference, or frontmatter field
- **obsidian_replace_in_note** — Literal or regex search-replace inside one note, body-only by default
- **obsidian_manage_frontmatter** — Get, set, or delete one frontmatter key
- **obsidian_manage_tags** — Add, remove, or list a note's tags in frontmatter, inline, or both
- **obsidian_delete_note** — Permanently delete a note, optionally after the user confirms (`OBSIDIAN_DELETE_ELICITATION`)
- **obsidian_open_in_ui** — Open a file in the Obsidian app, optionally in a new pane
- **obsidian_list_commands** — List command-palette commands (opt-in via `OBSIDIAN_ENABLE_COMMANDS`)
- **obsidian_execute_command** — Run a command-palette command by ID (opt-in via `OBSIDIAN_ENABLE_COMMANDS`)

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `bunx` (confidence: high):

```json
"mcpServers": {
  "obsidian-mcp-server": {
    "command": "bunx",
    "args": ["obsidian-mcp-server@latest"],
    "env": {
      "OBSIDIAN_API_KEY": "",
      "OBSIDIAN_ENABLE_COMMANDS": "",
      "OBSIDIAN_READ_PATHS": "",
      "OBSIDIAN_DELETE_ELICITATION": ""
    }
  }
}
```

**Requires environment variables:** `OBSIDIAN_API_KEY`, `OBSIDIAN_ENABLE_COMMANDS`, `OBSIDIAN_READ_PATHS`, `OBSIDIAN_DELETE_ELICITATION` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What obsidian-mcp-server does

The obsidian-mcp-server MCP server gives an MCP-compatible client access to an Obsidian vault through the Local REST API plugin. It covers both retrieval and controlled mutation: agents can read notes in several formats, browse files and folders, search note content, update sections, manage YAML frontmatter, and add or remove tags.

Reading supports raw content, a structured result containing content and metadata, a document map, or a selected section. Notes can be addressed by vault path, the active file, or a periodic note. Search supports text matching and JSONLogic queries; BM25-ranked Omnisearch results are available when the relevant Obsidian plugin is reachable.

Write operations distinguish between whole-file changes and targeted edits. Creating a note is supported, while replacing an existing file requires an explicit overwrite option. Other tools can append, prepend, or replace content at a heading, block reference, or frontmatter field. Deletion is permanent and requires a confirmation exchange.

## How it works

The server communicates with Obsidian through the Local REST API plugin and exposes the vault through MCP tools and resources. It can run as a STDIO process or as a local Streamable HTTP server. Resources include note data at `obsidian://vault/{+path}`, tag data at `obsidian://tags`, and server/plugin status at `obsidian://status`.

Path-based read and write permissions can restrict which vault locations are available. Listing and tag results reflect those restrictions when configured. File traversal has a default depth of two levels, a maximum depth of 20, and a 1,000-entry cap. Search results use cursors for pagination, while tag listings are ranked by usage and capped unless a larger limit is requested.

The obsidian-mcp-server MCP server also handles safety-related editing details. Repeated content at a patch target can be rejected, frontmatter replacements are checked after YAML parsing, and whole-file writes do not replace an existing note unless explicitly authorized. Command-palette listing and execution are disabled unless command access is opted into.

## Setup and configuration

Install and run the package as an MCP server, then provide an Obsidian API key through `OBSIDIAN_API_KEY`. Obsidian must have the Local REST API plugin available for the connection to work. The repository provides configuration paths for Claude Desktop, Cursor, and VS Code, and supports a Docker package as well as the published npm package.

Set `OBSIDIAN_ENABLE_COMMANDS=true` to expose command-palette listing and execution. `OBSIDIAN_READ_PATHS` can limit readable vault paths. The material also identifies `OBSIDIAN_DELETE_ELICITATION` as the setting associated with delete confirmation behavior. Exact values and client configuration should follow the repository's current setup instructions.

## Tools and capabilities

- Read notes as content, structured data, document maps, or sections.
- List notes and directories with depth, extension, and regular-expression filters.
- Search with text queries, JSONLogic, or available Omnisearch ranking.
- Create notes and perform targeted append, prepend, replace, and search-replace edits.
- Get, set, or delete individual frontmatter keys.
- Add, remove, or list tags in frontmatter, inline content, or both.
- Open files in the Obsidian interface and optionally use command-palette commands.

## Limitations and notes

Omnisearch mode is conditional on the plugin responding when the server starts and has an upstream 50-hit cap. Recursive listings and tag results can be truncated by their configured limits. Section operations depend on resolving a heading, block, or frontmatter target, and some section-creation behavior applies only to existing notes or specific options. Command tools require explicit opt-in, and deleting a note is permanent after confirmation.

_Full upstream README: https://allmcps.com/mcp/obsidian-mcp-server/readme_