Obsidian MCP: 3 servers and the CLI, set up for Claude Code

Updated 12 min read

An Obsidian vault is a folder of markdown files, so the simplest way to give an AI agent your second brain is to start an agent that edits files, such as Claude Code or Codex, in that folder (the next section walks through it). For agents that work through MCP, community servers expose the vault as tools, and Obsidian’s own CLI lets an agent drive the app from a terminal. All of them run on the machine where the vault lives.

How do I connect Claude Code or Codex to an Obsidian vault?

Point it at the folder. Obsidian’s docs say it stores notes as markdown plain text files in a vault, and a vault is a folder on your local file system. Other editors can change those files, and Obsidian refreshes to pick up the changes.

Claude Code reads and edits files and runs commands in the directory you start it from. Codex does the same from a project directory. So:

cd ~/path/to/your/vault
claude     # or: codex

To work from another project and still reach the vault, Claude Code’s --add-dir flag adds a directory Claude can read and edit:

claude --add-dir ~/path/to/your/vault

A few things help:

  • Write the conventions down. Put a CLAUDE.md for Claude Code, or an AGENTS.md for Codex and other coding agents, at the vault root. Say where new notes go, how you name them and that links use [[wikilinks]]. The guides to CLAUDE.md and AGENTS.md cover what goes in each.
  • Keep the agent out of .obsidian. Obsidian’s docs say that folder holds the vault’s settings, such as hotkeys, themes and community plugins.
  • Use Git for history. If you keep the vault in Git, Obsidian’s docs suggest adding .obsidian/workspace.json and .obsidian/workspaces.json to .gitignore, since they change whenever you open a file. Git then shows you what the agent changed.

This is the setup behind Andrej Karpathy’s LLM wiki: the agent edits the markdown on one side of the screen, and Obsidian shows the pages and the graph view on the other. For the folder layout and schema page, see running an LLM wiki in an Obsidian vault below. Three of the LLM wiki repos on GitHub we compared are built for Obsidian. To see a vault’s graph without opening Obsidian, open the folder in the wiki graph viewer; it reads the files in your browser and uploads nothing.

What Obsidian MCP servers are there?

The Obsidian MCP servers people use are community projects. Here are three of the most-starred on GitHub, with star counts read on 28 September 2026. Each description follows the project’s README. For chat plugins and local models, see which Obsidian AI plugins run agents inside the app.

Local REST API (2,971 stars)

coddingtonbear/obsidian-local-rest-api is a community plugin that runs inside Obsidian, so Obsidian has to be open. Besides its REST API, it includes an MCP server over Streamable HTTP at https://127.0.0.1:27124/mcp/. You find its API key under Settings → Local REST API.

Its tools include vault_list, vault_read, vault_write, vault_append, vault_patch (for a heading, block reference or frontmatter field), vault_move, vault_delete, search_simple (Obsidian’s built-in search), search_query (JsonLogic over note metadata), tag_list, command_execute and open_file. The README’s command for Claude Code:

claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \
  --header "Authorization: Bearer <your API key>"

The plugin serves HTTPS with a certificate it generates itself. The README says to trust its certificate authority, or to turn on the plain HTTP endpoint at http://127.0.0.1:27123/mcp/ in the plugin’s settings.

mcp-obsidian (4,449 stars)

MarkusPfundstein/mcp-obsidian is a Python server that reaches your vault through the Local REST API plugin. Install and enable the plugin first and copy its API key. The server needs Python 3.11 or later and runs with uvx mcp-obsidian. Its tools are list_files_in_vault, list_files_in_dir, get_file_contents, search, patch_content, append_content and delete_file. The README’s Claude Desktop config, with the default host and port filled in:

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uvx",
      "args": ["mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "<your API key>",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

MCPVault (1,675 stars)

bitbonsai/mcpvault is a Node.js server (version 20 or later) that works on the vault files directly. Obsidian does not need to be running and no plugin is required: your MCP client starts it as a local process and passes the vault path. It has 18 tools, including read_note, write_note, patch_note, move_note, search_notes, update_frontmatter, manage_tags and wiki_link. It refuses paths outside the vault, as well as .obsidian and .git. The README’s config for Claude Code, in ~/.claude.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"],
      "env": {}
    }
  }
}

The README also has examples for Claude Desktop, Codex, Cursor, Gemini CLI, OpenCode and others.

Does Obsidian have an official MCP server or CLI?

Obsidian’s help docs describe no MCP server of its own as of 28 September 2026. It does ship two command line tools an agent can use.

The Obsidian CLI controls the desktop app from your terminal. It needs the Obsidian 1.12.7 installer or later. Turn it on in Settings → General → Command line interface and follow the prompt to register it. The app must be running; if it is not, the first command launches it. An agent that runs shell commands can call it like any other tool:

obsidian search query="meeting notes"
obsidian backlinks file="Project Atlas"
obsidian unresolved
obsidian vault="Work" daily:append content="- [ ] Review the agent's notes"

unresolved lists links to notes that do not exist, and orphans lists notes with no incoming links. Obsidian’s docs add that its developer commands let agentic coding tools test and debug plugins.

Obsidian Headless, in open beta, is a command line client for Obsidian Sync and Obsidian Publish that runs without the desktop app. Among its uses, Obsidian lists giving “agentic tools access to a vault without access to your full computer”. Headless Sync needs Node.js 22 or later and an Obsidian Sync subscription.

Two more CLI commands matter when an agent reorganizes notes. obsidian move file="Old note" to=notes/archive/ and obsidian rename update internal links when Automatically update internal links is on in the vault settings, and Obsidian’s docs make no such promise for a plain mv. obsidian search:context query="pricing" returns matches as path:line: text, the grep-style output agents already know how to read.

Which Obsidian AI plugins run agents inside the app?

Obsidian publishes its community plugin list and every plugin’s download count on GitHub. On 20 November 2026 the list had 10,642 plugins with about 172.5 million downloads between them. 1,167 of them mention AI terms in their name or description (AI, LLM, GPT, Claude, Ollama, agent, MCP and similar), and those account for about 14.3 million downloads, 8.3% of the total. The most downloaded:

Plugin Downloads What it does License
Copilot 3,737,116 Chat and vault search; version 4 brings OpenCode, Claude Code and Codex into Obsidian AGPL-3.0
Claudian 2,769,687 Embeds Claude Code, Codex, OpenCode and other agents, with the vault as their working directory MIT
Smart Connections 1,276,563 Related notes and semantic search with a built-in local embedding model No standard license detected
Local REST API with MCP 864,765 The REST API and MCP server described above MIT
Text Generator 595,786 Generates text into notes with OpenAI, Google, Hugging Face and other providers MIT
Agent Client 340,795 Chat with Claude Code, Codex, Gemini CLI, Hermes Agent and other agents over the Agent Client Protocol Apache-2.0
Smart Composer 180,338 Chat that suggests edits to the open note, with MCP support MIT

Copilot is the 5th most downloaded of all 10,642 plugins and Claudian the 12th. Download counts are all-time totals, which favors older plugins, and Claudian does nothing except run agents. Agent Client is desktop only: it launches the agents installed on your machine as child processes and lets them run terminal commands, and they use the MCP servers and skills they already have. Check the last commit before you install: Copilot, Claudian and Agent Client all had commits in November 2026, while Smart Composer’s last commit was on 27 January 2026.

For notes that never leave your machine, Smart Connections’ README says it ships with a local embedding model and is private and offline by default. Local GPT (108,973 downloads, MIT) runs on local models through Ollama.

Rules and permissions for Claude Code in a vault

Claude Code reads the CLAUDE.md in the folder you start it from at the beginning of every session, and Anthropic’s memory docs suggest keeping each one under 200 lines. In a code repository /init drafts one from the codebase; a vault has nothing for it to read, so write this one yourself. A starting point:

# Vault rules

This is my Obsidian vault. You maintain notes/; I read it in Obsidian.

## Where things go
- Captures land in inbox/. File what they say into notes/,
  then move the capture to inbox/done/.
- raw/ holds sources. Read them. Never edit, move or delete them.
- One topic per page in notes/. File names: lowercase-with-dashes.md
- Never touch .obsidian/.

## Links
- Link pages with [[wikilinks]] by file name, without .md.
- Before you create a page, search for one on the topic and update it instead.
- Rename or move notes with `obsidian rename` or `obsidian move`, not `mv`.

If Codex or another coding agent works in the same vault, put the shared rules in AGENTS.md and make @AGENTS.md the first line of CLAUDE.md. By default Claude Code reads AGENTS.md only when there is no CLAUDE.md in the working directory or above it, so the import keeps both agents on one set of rules.

A deny rule keeps Claude out of folders whatever the conversation says. In the vault’s .claude/settings.json:

{
  "permissions": {
    "deny": [
      "Edit(/.obsidian/**)",
      "Edit(/raw/**)"
    ]
  }
}

In project settings, a path that starts with a single / is relative to the project folder, here the vault. An Edit rule on raw/ still lets Claude read your sources. Anthropic’s permissions docs note that these rules cover Claude’s own file tools and the file commands it recognizes in Bash, and not a Python or Node script that opens files itself; for that, they point to the sandbox.

A routine you repeat, such as filing the inbox, can become a skill. Claude Code’s skills docs say a SKILL.md in .claude/skills/<name>/ creates a /<name> command, so .claude/skills/inbox/SKILL.md gives you /inbox:

---
description: Files inbox/ captures into notes/. Use when I say "process the inbox".
---

For each file in inbox/ (not inbox/done/):
1. Find the notes/ pages it belongs to. Search before creating a page.
2. Update those pages, or write a new one. Link with [[wikilinks]].
3. Move the capture to inbox/done/.
Then list what you changed and anything you were unsure about.

Running an LLM wiki in an Obsidian vault

In Andrej Karpathy’s LLM wiki the agent writes the notes: you keep sources in one folder, and the agent writes and maintains linked pages from them, which you read in Obsidian. Give the wiki its own vault, or one top-level folder in your vault, so your own notes and the agent’s pages stay apart in search and in the graph. A layout close to the gist:

wiki/
  SCHEMA.md      # the rules every maintainer reads first
  index.md       # every page, one line each
  log.md         # append-only: ## [YYYY-MM-DD] action | subject
  raw/           # sources; never edited
    assets/      # images, set as Obsidian's attachment folder
  entities/
  concepts/
  queries/       # answers worth keeping

Keep the rules in SCHEMA.md, a page you can read and edit in Obsidian, and point each agent at it: @SCHEMA.md in CLAUDE.md, or a line in AGENTS.md saying to read it before any task. The gist also suggests setting Settings → Files and links → Attachment folder path to raw/assets/, so a clipped article’s images are saved where the agent can read them.

Who maintains the wiki is the main choice:

  • A coding agent started in the folder, such as Claude Code or Codex. You steer each ingest and grow the schema as you go.
  • Hermes Agent’s llm-wiki skill (version 2.1.0, MIT). It is now an optional skill, installed with hermes skills install official/research/llm-wiki. Set WIKI_PATH to the folder Obsidian opens; without it the skill uses ~/wiki. Before any ingest, query or lint it reads SCHEMA.md, index.md and the last 20 to 30 log entries, and it stores a sha256 of each raw source so it can tell on re-ingest whether a source changed.
  • The Karpathy LLM Wiki plugin (73,061 downloads, Apache-2.0), for no terminal at all. It needs Obsidian 1.11.4 or newer on desktop or mobile, writes its pages under wiki/, and lists more than 15 model providers, including Ollama and LM Studio for local models.
  • The Auto LLM Wiki plugin (4,103 downloads), if you want to preview every change. It sends new or changed raw files to an OpenAI-compatible endpoint you configure, shows a plan of file changes, applies it only after you confirm, and rolls back if any part fails.

Download counts are from Obsidian’s plugin stats on 20 November 2026.

Graph view is where you check the wiki’s shape. Settings from Obsidian’s graph view docs that suit a wiki: a color group per folder with search terms such as path:entities and path:concepts; the Orphans filter, which shows pages an ingest wrote but never linked in; Existing files only turned off, which shows pages that are linked to but not written yet; a local graph on one concept page with the depth raised; and Animate, which replays the graph in the order pages were created.

What are the limits of a local vault for AI agents?

  • It lives on one machine. A vault is a folder on your local file system, and every option above runs where that folder is. Obsidian Sync, Headless Sync, Git and other sync services can copy the vault to another computer, but then each agent works on its own copy.
  • Agents elsewhere cannot reach localhost. The Local REST API serves on 127.0.0.1, mcp-obsidian connects to 127.0.0.1 by default, and MCPVault is a local process your client starts. For an agent in the cloud, such as Claude on the web, Grok Bot or a bot in a chat app, 127.0.0.1 is the cloud machine, not your laptop. The Local REST API and the CLI also need Obsidian open. A hosted server, such as the Google Drive MCP server for a team’s Drive files, answers at a public address that agents on any machine can reach.
  • Two agents can write the same file. A folder of files does not record which agent changed a line, and nothing stops two agents from editing one note at once. The Local REST API’s patch accepts a version for optimistic concurrency, so a stale edit fails instead of overwriting a newer one. Editing the files directly has no such check.

What if your agents run on other machines or in chat apps?

Then a hosted wiki is the alternative. Dexio is a hosted wiki for AI agents. Claude Code, Codex, Cursor, Claude, ChatGPT, Hermes and OpenClaw list, read, search, write, edit, move and link markdown pages through a remote MCP server at https://app.dexio.wiki/mcp. You read the pages in your browser at https://app.dexio.wiki, with the link graph. It is free for one person.

Dexio is separate from your vault. It does not sync with Obsidian, open a vault or import one, so you decide which notes live where. Pages link with [[wikilinks]]. Every change is kept, with the name of the agent that made it, and passing base_version stops one agent from overwriting another’s edit. You can download the whole wiki as a zip with one markdown file per page.

To connect an agent, send it this message:

Connect yourself to my Dexio wiki. The steps are at https://dexio.wiki/agents.md: read the whole file, not a summary, and follow them.

The guides for Claude Code, Codex, Cursor, Claude, Hermes and OpenClaw cover each one, Hermes Agent vs OpenClaw compares those two, and the LLM wiki guide covers how a wiki grows from linked pages. All guides are at /guides.

Sources

Ask a question

Ask anything about Dexio.

About
We reply by email.