cyanheads/obsidian-mcp-server

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

Overview

obsidian‑mcp‑server is a bridge that lets AI agents (or any MCP‑compatible client) read and edit notes stored in an Obsidian vault. It talks to the Obsidian Local REST API plugin and exposes a set of MCP tools and resource URLs over either a simple stdio interface or a lightweight HTTP server. The server handles authentication, folder‑scoped permissions, and a rich set of operations such as:

  • fetching a note (full content, a single heading, or a parsed document map)
  • listing notes, tags, or command‑palette entries
  • searching notes with plain‑text, JSONLogic, or BM25 (via the Omnisearch plugin)
  • creating, appending, patching, or replacing sections, blocks, and front‑matter
  • managing tags and front‑matter keys
  • deleting notes (with optional user‑confirmation) and opening notes in the Obsidian UI.

All responses are JSON‑RPC‑style objects that include detailed error codes and recovery hints, making them easy for autonomous agents to consume and act on.

Key Features

Feature What it does
MCP‑based API Implements the Model Context Protocol (MCP) so any MCP client (Claude Desktop, Cursor, VS Code, custom bots) can call the tools via stdio or HTTP.
Fine‑grained permissions Folder‑scoped read/write policies, read‑only mode, and optional JWT/OAuth auth protect the vault.
Rich note manipulation Write whole files, replace a single heading, block, or front‑matter field, and perform regex‑based search‑replace.
Tag & front‑matter management Add/remove/list tags (front‑matter, inline, or both) and get/set/delete arbitrary front‑matter keys.
Search flexibility Text search, JSONLogic queries, or BM25‑ranked Omnisearch (if the Omnisearch plugin is present).
Agent‑friendly output Errors include reason, JSON‑RPC code, and a recovery.hint; mutating tools report size deltas and ambiguity data.
Pluggable storage & logging In‑memory, filesystem, Supabase, Cloudflare KV/R2/D1 back‑ends; structured logging with optional OpenTelemetry tracing.
Multiple deployment options Run via Bun, Node (npx), Docker, or as a Streamable HTTP server.

Typical Use‑Case Flow

  1. Setup – Install the Obsidian Local REST API plugin, generate an API key, and configure OBSIDIAN_API_KEY (and optionally OBSIDIAN_BASE_URL).
  2. Start the server – bun run start:http for an HTTP endpoint or bunx obsidian-mcp-server@latest for stdio.
  3. Call a tool – An MCP‑compatible client sends a JSON‑RPC request, e.g. obsidian_get_note to fetch a note, obsidian_append_to_note to add a bullet, or obsidian_search_notes to find relevant content.
  4. Process the response – The client reads the structured result, checks for recovery.hint on errors, and may issue follow‑up calls (e.g., confirm deletion via obsidian_delete_note with elicitation).
  5. Iterate – Agents can chain tools to build, edit, and organise knowledge inside the vault autonomously.

Installation & Quick Start

# Clone & install (Bun preferred)
git clone https://github.com/cyanheads/obsidian-mcp-server.git
cd obsidian-mcp-server
bun install

# Copy env template and add your API key
cp .env.example .env
# edit .env → set OBSIDIAN_API_KEY=your‑key

# Run via stdio (Bun) or Docker
bunx obsidian-mcp-server@latest   # stdio
# or
docker run -i --rm -e OBSIDIAN_API_KEY=… ghcr.io/cyanheads/obsidian-mcp-server:latest

For HTTP:

MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=… bun run start:http
# server now at http://127.0.0.1:3010/mcp

Who Might Use This?

  • AI agents that need to read/write personal knowledge bases stored in Obsidian.
  • Automation scripts for bulk note updates, tag clean‑up, or periodic‑note generation.
  • Developer tools that want to expose Obsidian vaults to external IDEs or CLI utilities via a standard protocol.
  • Research pipelines that treat an Obsidian vault as a structured data store and need programmatic access.

Limitations & Gotchas

  • Relies on the Obsidian Local REST API plugin; the server cannot function without it.
  • Certain operations (e.g., heading writes on Windows CRLF files) have known quirks on older plugin versions.
  • Deleting notes is irreversible at the API level; only Obsidian’s local trash can recover them.
  • The server does not provide its own search engine – it forwards to Omnisearch if that plugin is installed.
  • Permissions are enforced at the folder level; mis‑configured OBSIDIAN_READ_PATHS/OBSIDIAN_WRITE_PATHS may unintentionally block access.

License

Apache 2.0 – free to use, modify, and distribute.

Related

  • Project
    MarkusPfundstein/mcp-obsidian

    An MCP server that enables AI assistants to interact with Obsidian vaults by reading, searching, and editing notes via the Local REST API plugin.

  • Project
    bitbonsai/mcpvault

    A local MCP server that enables AI assistants to read, search, and edit notes within an Obsidian vault directly via the file system.

  • Project
    coddingtonbear/obsidian-local-rest-api

    A secure local REST API and MCP server for Obsidian that allows scripts and AI agents to programmatically read, write, and search your vault.

  • Project
    StevenStavrakis/obsidian-mcp

    A local Model Context Protocol server that enables AI assistants to safely read and modify Obsidian vaults by interacting directly with Markdown files.

  • Project
    aaronsb/obsidian-mcp-plugin

    An Obsidian plugin that turns your vault into an MCP server, allowing AI assistants to read, write, and navigate your notes as a connected knowledge graph.