Obsidian MCP Setup 2026: Local REST API Complete Guide

TL;DR + what you actually need

Two pieces have to be in place before Obsidian MCP works. Most setup pain in our inbox comes from people trying to install the MCP server without the plugin underneath, or the other way round.

• Piece 1 — Obsidian Local REST API plugin. Community plugin by coddingtonbear. Install from inside Obsidian (Settings → Community plugins → Browse). Generates the API key you’ll paste into your MCP client.
• Piece 2 — the MCP server. Usually mcp-obsidian by MarkusPfundstein, launched via uvx mcp-obsidian. Reads the API key from OBSIDIAN_API_KEY, talks to the plugin on 127.0.0.1:27124.
• Default port: 27124 (HTTPS, self-signed certificate). HTTP on 27123 exists but is off by default and not recommended.

The fast install paths, in case you came here for the one-liner:

• Claude Code: claude mcp add obsidian uvx mcp-obsidian -e OBSIDIAN_API_KEY=...
• Claude Desktop / Cursor / VS Code / Windsurf: copy the snippet from the install panel below — same JSON shape, different config-file location.
• OpenCode: a local-shape entry with command: ["uvx", "mcp-obsidian"] — full snippet in the OpenCode section.

The rest of this guide explains why the two pieces exist, walks through every tool method, shows seven real vault workflows, covers the security trade-off (the API has full read/write on your notes), and ends with troubleshooting for the failure modes we see most often.

What Obsidian MCP actually does

Most Obsidian users we know hit the same wall: their vault is brilliant for capture but a chore for synthesis. You’ve got 4,000 notes, a working graph, daily-note rituals — and the moment you want to ask “what did I write about distributed locks across all my engineering notes last quarter,” you’re back to grep and Cmd-O. Obsidian MCP fixes that class of problem by giving an LLM-shaped tool surface over the vault.

Concretely: an Obsidian MCP server exposes vault operations — list, read, search, write, patch, append, delete — as MCP tools. Once registered in Claude Desktop, Claude Code, Cursor, or any MCP-aware agent, the model can call those tools directly during a conversation. You ask “summarise everything I wrote about the auth migration last month,” the agent calls search with relevant terms, then get_file_contents on the top hits, then writes the summary. No copy-paste, no manual grep.

The reason the project exists in two pieces (plugin + server) is architectural. Obsidian itself doesn’t ship an HTTP server, but its plugin API can run one inside the app. The Local REST API plugin by coddingtonbear does exactly that: it spins up an HTTPS server on 127.0.0.1:27124 with endpoints for vault operations. The MCP server (e.g. MarkusPfundstein/mcp-obsidian) is a translation layer: it converts MCP tool calls from your agent into HTTP requests against the plugin’s endpoints, then converts the responses back into MCP results. Two pieces, one job.

A second thing worth knowing: the MCP server is stateless and local. It doesn’t store your notes, doesn’t phone home, and only knows about your vault while Obsidian is open. Closing Obsidian breaks the chain — that’s the trade-off for keeping the whole thing offline and self-hosted.

How the plugin-plus-MCP flow works

When your agent calls a tool, four things happen in order:

1. MCP client → MCP server. Claude Code (or whatever) sends an MCP tool call (say search with query “auth migration”) to the locally-running mcp-obsidian process via stdio.
2. MCP server → Local REST API. mcp-obsidian translates that into an HTTPS request against https://127.0.0.1:27124/search/, with your API key in the Authorization header.
3. Plugin → Obsidian internals. The Local REST API plugin runs the query through Obsidian’s own search index and returns matching files plus snippet context.
4. Back up the chain. Plugin returns JSON, MCP server wraps it as an MCP tool result, client hands it to the model. Total round-trip: usually under 100ms on a warm vault.

The reason this matters: any failure in the chain surfaces differently. If the plugin isn’t enabled, you get connection-refused. If the API key is wrong, you get 401. If the path doesn’t exist, the MCP server still talks back, but with an empty-result tool response. Knowing which layer is screaming saves a lot of time when debugging.

Install (every client)

The install is two-phase. Phase 1: set up the plugin inside Obsidian and grab the API key. Phase 2: wire the MCP server into your agent. Skip either and the whole chain breaks.

Phase 1 — the Local REST API plugin

Open Obsidian. Go to Settings → Community plugins. If you’ve never used community plugins, you’ll need to click Turn on community plugins once. Then click Browse, search for Local REST API (author: coddingtonbear), and click Install. Once installed, toggle it on in the community plugins list.

Now find the plugin’s settings pane in the sidebar (Settings → Local REST API). At the top you’ll see a long random string labelled API key — copy it, you’ll paste it into your MCP client config in phase 2. Below that, the plugin lists the URLs it’s serving (HTTPS on 27124 by default). You can change the port, bind to a different interface, or enable the unencrypted HTTP variant on 27123 — but the defaults are sensible and the rest of this guide assumes them.

One macOS / Linux gotcha: the cert is self-signed, so tools that aren’t configured to trust it will refuse the connection. The plugin pane has a Download Certificate button — most MCP server packages handle the self-signed cert internally, so you only need this if you’re calling the API from a generic HTTPS client like curl.

Phase 2 — the MCP server

For Claude Desktop, Cursor, VS Code, Windsurf, and most other clients in the catalog, the install panel below has the exact JSON snippet you need. Pick your client’s row, copy the snippet, paste it into the relevant config file, swap in your API key, and restart the client. The panel pulls configs directly from our catalog so it stays in sync as the upstream package evolves.

One-line install · Obsidian Local REST API

Open server page

Install

Cursor

One-click install

VS Code

One-click install

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Two important notes about the snippets above:

• Replace the API key placeholder. Every snippet has OBSIDIAN_API_KEY=your-api-key-here (or similar). Paste the key you copied from the plugin pane in phase 1 — without that, the MCP server starts but every tool call returns 401.
• The Obsidian app must be running. Plugin = inside Obsidian = only serves while Obsidian is open with the plugin enabled. If your agent reports connection errors and the MCP server looks healthy, check whether you closed Obsidian.

The Claude Code one-liner is the most common path we’ve seen searched for:

claude mcp add obsidian uvx mcp-obsidian \
  -e OBSIDIAN_API_KEY=your_key_here \
  -e OBSIDIAN_HOST=127.0.0.1

Add --scope project to write to .mcp.json at the repo root so it travels with the project. Confirm registration with claude mcp list. Full details on the Claude Code client page.

Add Obsidian to OpenCode

OpenCode (the open-source TUI agent) isn’t in the standard install panel above. Edit OpenCode’s config directly — commonly at ~/.config/opencode/config.json, or run opencode config print to confirm the path. Local-stdio shape:

{
  "mcp": {
    "obsidian": {
      "type": "local",
      "command": ["uvx", "mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "your-key-here",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

Restart OpenCode (opencode in a new shell) and Obsidian shows up in the tool list. If you’re still picking between OpenCode and the other CLI agents, our Goose vs Cline vs Aider vs Claude Code vs OpenCode breakdown covers the trade-offs.

Browse every client and its config path at mcp.directory/clients.

The seven tools, walked through

mcp-obsidian exposes seven tools, per the MarkusPfundstein repo README. Each maps to one or more endpoints in the Local REST API plugin. Tool names are the exact strings you’ll see in your agent’s tool catalogue.

1. list_files_in_vault

Returns the top-level files and folders in your vault. No arguments. Useful for the agent to get its bearings before diving in. Returns folder names and file paths.

2. list_files_in_dir

Returns files inside one folder, given a path relative to the vault root. Argument: dirpath: "Daily Notes/2026" returns the year’s daily notes. The agent often calls this iteratively when narrowing down a search.

3. get_file_contents

Reads the full markdown of a single note. Argument: filepath: "Projects/auth-migration.md". Returns the raw markdown including frontmatter. This is the most-called tool in any retrieval workflow — the agent search-then-reads, search-then-reads.

4. search

Free-text search across the vault using Obsidian’s own search index. Argument: query: "distributed locks" returns matching files plus snippet context. The Local REST API supports the same operators as Obsidian’s in-app search, so path:, tag:, and other modifiers work.

5. patch_content

The most powerful and least-used tool. Inserts content relative to a heading, block reference, or frontmatter field — without rewriting the whole file. Useful for agents that need to add a row to a table, append under a specific H2, or update a frontmatter field. Arguments are documented in the plugin’s API spec; check the repo README for the latest signature.

6. append_content

Appends to the end of a note. Creates the note if it doesn’t exist. The bread-and-butter write tool — most “add a journal entry” or “log this” agent workflows go through this. Arguments: filepath, content.

7. delete_file

Deletes a note by path. Use with care — there’s no recycle bin on the API side, only Obsidian’s own version history (if you’ve enabled it) and Obsidian Sync history if that’s on. Most agent workflows we’ve seen deny this tool by default and only enable it for specific cleanup tasks.

The tool set may expand — the README is the source of truth, since the package version on PyPI ticks forward. As of this writing the seven tools above are stable.

Recipes

Seven workflows where Obsidian MCP earns its keep. We assume the plugin is installed, the MCP server is registered at user scope, and Obsidian is open with your vault loaded.

Recipe 1 — “What did I write about X?”

The killer app. Prompt: “Summarise everything I’ve written about the auth migration in the last month. Cite the note titles.” The agent calls search with relevant terms, then get_file_contents on the top hits, then synthesises. We’ve watched this turn a 30-minute archaeology session into a 90-second ask. Works best when your notes already tag concepts consistently.

Recipe 2 — Daily-note generation

If you keep a daily note, an agent can populate it from inputs you describe in chat. Prompt: “Write today’s daily note. Today I shipped the auth fix, debugged the Stripe webhook, and read two papers on liquid time-constant networks.” The agent calls append_content against Daily Notes/2026-05-11.md with a structured entry. Pair with a Claude Code skill or Claude Desktop project so the format stays consistent across days.

Recipe 3 — Tag-driven literature review

You tag papers #paper and synthesise periodically. Prompt: “Find every note tagged #paper from the last six months. Group by topic, summarise the key finding per group.” The agent calls search with tag:#paper, batches get_file_contents, returns a grouped synthesis. Companion to our literature-review skill guide if you want a more structured pipeline.

Recipe 4 — Cross-vault Q&A in your IDE

You’re writing code in Cursor or Claude Code and need to remember “wait, did I already figure out how to do this last quarter?” Prompt the agent (which has both vault access and code-editor access): “Search my Obsidian vault for distributed locks. If I’ve solved this before, surface the approach.” Hits land in chat, the agent quotes the relevant paragraphs, you decide whether to apply them.

Recipe 5 — Spec-doc generation from chat

Long Claude/Cursor conversations often produce shippable design docs by accident. Capture them with a prompt like: “Save this conversation as a spec doc at Projects/auth-v2/spec.md. Frontmatter: status: draft, owner: me, last-touched: today.” The agent calls append_content (or creates the file) and you’ve permanent-ised the conversation in your knowledge base without copy-pasting.

Recipe 6 — Vault hygiene pass

Periodically the agent can scan for orphaned notes, broken links, or empty files. Prompt: “List all files in /Inbox older than 30 days. For each, suggest where it should be filed or flag for deletion.” The agent calls list_files_in_dir then get_file_contents per file, returns a triage list. You approve the moves; the agent executes them.

Recipe 7 — Second-brain prompt that always uses Obsidian

For knowledge-work flows you do constantly, bake the vault into a Claude Code skill or Claude Desktop project:

---
name: vault-aware-writer
description: |
  Writing helper that grounds answers in my Obsidian vault.
  Always searches the vault before answering questions about
  topics I might have written about previously.
---
For any question about a topic I might have written notes on,
first call search with the topic keywords, then get_file_contents
on the top 3 hits, then synthesise. Cite the note titles in your
response so I can navigate to the source.

The skill auto-grounds answers in your notes, makes citations the default, and stops the model from inventing things you already wrote down.

Security: the API has your whole vault

Worth pausing on this. The Local REST API has full read and write access to every note in the active vault — that’s how it can be useful. The implication: anyone with your API key can read or destroy your vault programmatically.

What the plugin does right by default:

• Binds to 127.0.0.1 (localhost only) so remote machines can’t reach it without you opening the door.
• Uses HTTPS with a self-signed cert — eavesdropping on localhost is hard but not impossible on a shared machine.
• Requires an API key on every request. The key is long, random, and per-vault.

What you should still be careful about:

• Don’t commit the API key. Treat it like a database password. Use env vars in your MCP client config. If you use .mcp.json at the repo root, gitignore it or use the project’s secrets-injection pattern.
• Be aware of agent autonomy on the delete_file tool. Most clients let you require manual approval for destructive tools. Turn that on. Recovery from a rogue agent is messy — Obsidian’s file history plugin or Obsidian Sync are your fallback.
• Don’t expose the API publicly. Tempting if you want vault access from another machine. Don’t — at minimum, tunnel over SSH or Tailscale so the API stays on a private network. Direct public exposure is one stolen key away from data exfiltration.
• Audit what you ask the agent to write. Long-running agents that auto-append journal entries can corrupt the vault quietly. Sample their output for a few days before trusting an autonomous loop.

None of this is panic-inducing — it’s the standard trade-off of giving an LLM real tools — but it’s worth surfacing because the install path doesn’t.

Obsidian Canvas + MCP

Canvas files (.canvas) are JSON under the hood — the visual graph view is rendered from that JSON at edit time. The Local REST API treats them as regular files, so the MCP server can read, search, and append to canvases just like any markdown note. What it cannot do is manipulate the visual layout — there’s no canvas-aware endpoint that positions nodes or wires edges.

Practically, that means:

• Agents can read a canvas, summarise the cards in it, and add new cards by editing the JSON. The new cards will render in Obsidian when you next open the file.
• Agents can’t reposition existing cards visually, draw arrows between nodes, or recompute layout. Those operations need a canvas-aware UI layer that the plugin doesn’t expose.
• If your workflow is heavy on visual canvas manipulation, plan to do that in Obsidian proper — and use MCP for the content-editing parts (adding cards, summarising clusters, etc.).

Canvas support is the most common “does this work with X feature?” question we get on the Obsidian MCP page, hence the dedicated section.

Pricing

Three things have prices in this stack; all are generous.

• Obsidian itself: free for personal use. The Commercial licence ($50/year per user) kicks in only if Obsidian is used for for-profit work at a company larger than two people. Catalyst (early access, custom themes) is a one-time donation. Obsidian Sync ($4/mo) and Publish ($8/mo) are optional add-ons unrelated to the MCP setup.
• Local REST API plugin: free, MIT-licensed, no signup, no telemetry.
• MCP server (mcp-obsidian and friends): free, MIT-licensed, distributed via PyPI / npm. No external service involved — everything runs on your machine.

Total cost to run the full Obsidian-plus-MCP stack for personal knowledge work: $0. Even at a small company the marginal cost is just Obsidian’s commercial licence per user. The MCP layer itself never charges.

Troubleshooting

When to switch to something else

Obsidian MCP is excellent for personal-vault knowledge work where the notes already live in Obsidian and you want to add an agent on top. It’s not the right tool for every knowledge-base job.

• Your notes live in Notion, Confluence, or a company wiki: use the dedicated MCP server for that platform. Our best knowledge-base MCP servers (2026) comparison covers the alternatives.
• You want shared / team-wide vault access: the Local REST API is single-machine by design. You’d need every team member to run their own MCP server pointing at their local Obsidian, or move to a hosted knowledge platform.
• You want semantic search, not keyword search: the Local REST API uses Obsidian’s built-in search, which is keyword-based with operators. For embeddings-driven retrieval over your notes, pipe the vault into a separate vector store via one of the MCP servers in our vector-DB comparison.
• You’re uncomfortable giving an agent full write access to your notes: start with read-only by disabling the write tools in your client’s allow-list, or use the community read-only fork pmmvr/obsidian-api-mcp-server which is intentionally scoped to read + search only.

For most Obsidian users we’ve talked to though, the MCP setup is the right call — it’s the cheapest, most local, most flexible way to put an agent on top of a vault you already trust.

FAQ

Sources

• Obsidian Local REST API plugin (coddingtonbear): github.com/coddingtonbear/obsidian-local-rest-api
• mcp-obsidian server (MarkusPfundstein): github.com/MarkusPfundstein/mcp-obsidian
• Catalog entry on MCP.Directory: /servers/obsidian-local-rest-api
• Community alternative (TypeScript, npx-installable): j-shelfwood/obsidian-local-rest-api-mcp
• Obsidian plugins marketplace: obsidian.md/plugins