Obsidian MCP Server

Name: Obsidian MCP Server
Author: cyanheads

@cyanheads

Repository Homepage

About Obsidian MCP Server

Read, write, search, and surgically edit Obsidian vault notes, tags, and frontmatter via MCP. STDIO or Streamable HTTP.

#typescript #mcp #note-taking #knowledge-base #obsidian #ai-tools #llm #llm-agent #model-context-protocol

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-server@latest"
      ],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

Tools

Read a note as raw content, full structured form (content + frontmatter + tags + stat, with optional outgoing links), structural document map, or a single section.

List notes and subdirectories under a vault path. Recursive walk (default depth 2, max depth 20; 1000-entry cap) with optional `extension` and `nameRegex` filters.

List every tag found across the vault with usage counts, including hierarchical parents. Optional `nameRegex` post-filters the result set.

List Obsidian command-palette commands, optionally filtered by `nameRegex` on display name. **Opt-in via `OBSIDIAN_ENABLE_COMMANDS=true`** (paired with `obsidian_execute_command`).

Search the vault by text, JSONLogic, or BM25-ranked Omnisearch (when the plugin is reachable). Results paginate via opaque cursors.

Create a note, replace a single section in place, or — with `overwrite: true` — clobber an existing file. Refuses whole-file writes against an existing path by default.

Append content to a note. Without `section`, creates the file if missing. With `section`, appends to a specific heading, block, or frontmatter field (file must exist).

Surgical `append` / `prepend` / `replace` against a heading, block reference, or frontmatter field.

Body-wide search-replace inside a single note. Literal or regex matching with whole-word, whitespace-flexible, and case-sensitivity options; supports capture-group replacement.

Atomic `get` / `set` / `delete` on a single frontmatter key.

Add, remove, or list tags. Defaults to the frontmatter `tags:` array; `location: 'inline'` or `'both'` opts into mutating the note body.

Permanently delete a note. Elicits human confirmation when the client supports it.

Open a file in the Obsidian app UI, with `failIfMissing` and `newLeaf` toggles.

Execute an Obsidian command-palette command by ID. **Opt-in via `OBSIDIAN_ENABLE_COMMANDS=true`.**

Overview

What is Obsidian MCP Server?

Obsidian MCP Server lets AI agents read, write, search, and surgically edit Obsidian vault notes, tags, and frontmatter via the Model Context Protocol. It offers 14 tools and 3 resources, and supports STDIO or Streamable HTTP transport. It is built for developers and power users who want to automate or integrate with their Obsidian notes.

How to use Obsidian MCP Server?

Install via npm (npx -y obsidian-mcp-server) or Docker (ghcr.io/cyanheads/obsidian-mcp-server). Set the OBSIDIAN_API_KEY environment variable to your Obsidian Local REST API key. Configure the server in your MCP client (e.g., Claude Desktop, Cursor, VS Code) with the appropriate command and environment variable. The server can also be installed via a dedicated MCP bundle.

Key features of Obsidian MCP Server

Read notes as raw content, full structure, document map, or section.
Write, append, patch, and search‑replace notes with surgical precision.
Manage frontmatter and tags (frontmatter, inline, or both).
Search by text, JSONLogic, or Omnisearch BM25 ranking.
List notes, tags, and Obsidian commands.
Create notes safely with overwrite protection.
Execute Obsidian command‑palette commands (opt‑in).
Paginate search results via opaque cursors.
Supports optional Omnisearch plugin integration.

Use cases of Obsidian MCP Server

Automate note creation, updates, and tag management in a vault.
Search and retrieve notes programmatically for AI‑powered knowledge bases.
Perform bulk or targeted edits on frontmatter, headings, or inline tags.
Integrate Obsidian with MCP‑compatible agents for note‑taking workflows.

FAQ from Obsidian MCP Server

What transports does the server support?

STDIO and Streamable HTTP are both supported.

Does it require an API key?

Yes, you must set the OBSIDIAN_API_KEY environment variable with your Obsidian Local REST API key.

How can I avoid accidentally overwriting a note?

The obsidian_write_note tool refuses to clobber an existing file unless overwrite: true is explicitly set. Use obsidian_patch_note or obsidian_append_to_note for in‑place edits.

Does the server support Omnisearch?

Yes, if the Omnisearch plugin’s HTTP server is reachable at startup, the obsidian_search_notes tool offers an Omnisearch mode with BM25 ranking, quoted phrases, exclusions, and path/ext filters.

How do I paginate search results?

Pass the nextCursor value from the previous response as the cursor parameter for subsequent pages. Omit cursor for the first page.

Comments

More Memory & Knowledge MCP servers

Zettelkasten MCP Server

entanglr

A Model Context Protocol (MCP) server that implements the Zettelkasten knowledge management methodology, allowing you to create, link, explore and synthesize atomic notes through Claude and other MCP-compatible clients.

159