OBSIDIAN
Protocols / MCP Overview.md

Model Context Protocol

#protocol #architecture #agents

What it is

Local-first MCP server for working with an Obsidian vault.

No Obsidian plugin required
No API key required
No cloud service required
No Obsidian running in the background

This is for people who want MCP clients to work directly with markdown files on disk.

WHAT IT DOES

It lets MCP clients work with your vault to: read and search notes create and update notes generate summaries, status reports, and release notes automate local knowledge workflows All directly against your local markdown files.
Secure by design.Permission scopes are explicit and revocable. Nothing flows unless you said it could.
Model agnostic.Works across providers — your stack stays portable.
Composable.Servers chain. Tools nest. Workflows snap together.
● 1,248 words 7,914 chars 37 backlinks 3 properties ● Synced
VAULT AGENT
notes/protocols
tool: read_file
scope: read+write
tool: write_file
MCP
Model Context
Protocol
AGENT
Agent

Task

00:00:14
Scan my Lattice vault via MCP and synthesize a one-page summary of how the architecture notes fit together — flag any contradictions.
Running 3 tools active

Best for

5 steps
Codex users who want safe local access to an Obsidian vault


Claude Desktop, Cline, Cursor, and other MCP clients that can run a local Python serv
Done
Discover vault structure & notes
Done
Extract architecture references
In progress
Synthesize cross-note summary
Queued
Write output to vault note
Queued

MCP Connection

Connected
KIKA Vault
mcp://lattice.local

File changes

since 00:00:08
03-Resources/Protocols/Architecture Summary.md
+ Created · streaming
+1.4 KB
Ask Helix to do something with your vault…
Add context Attach Mode: Plan ▾
Helix is connected to your vault via MCP v1.2 · session 7b41…
scroll
Why obsidian-codex-mcp

Built on one principle:
your data doesn't leave your machine.

No plugin to install. No API key to generate. No Obsidian running in the background. Just your vault, your agent, your disk.

01 · local-first

Zero cloud surface

Reads markdown files directly from disk. No network calls, no sync service, no remote API. Your vault stays where you put it.

02 · plugin-free

No app runtime required

Unlike REST-API bridges, this server doesn't need Obsidian running. Point it at a vault path and it works directly with markdown files on disk.

03 · no api key

Minimal setup friction

No account, no key, no cloud subscription. Clone, install, point at vault. That's the core flow.

04 · model-agnostic

Built for MCP clients

Codex, Claude Desktop, Cline, Cursor — or any future MCP-compatible agent that can run a local Python MCP server.

05 · secure

Scoped by design

Operates only within your configured vault directory. No system access, no network, no surprises. Permission scopes are explicit and revocable.

06 · composable

Plays well with others

Stack it alongside other MCP servers. Combine with memory tools, automation pipelines, and agent loops. Servers chain. Tools nest. Workflows snap together.

Capabilities

What your agent can do with your vault

Full read/write access to your knowledge base. Search, summarize, create, update — all from within your agent's context.

01

Read & search notes

Full-text search across the entire vault. Retrieve notes by path, content pattern, or tag.

02

Create & update notes

Write new markdown files or patch existing ones. Heading-aware edits, frontmatter-safe.

03

Generate summaries & reports

Synthesize across multiple notes. Build weekly reviews, project briefs, release notes, architecture digests.

04

Automate local knowledge workflows

Create note templates, reorganize vault structure, extract tasks, pipe output back to disk — all inside your agent loop.

05

Navigate vault structure

List files, traverse folders, map directory trees. Give your agent a complete picture of your vault topology.

Config
{
  "mcpServers": {
    "obsidian-codex-mcp": {
      "command": "/absolute/path/to/obsidian-codex-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/obsidian-codex-mcp/server.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/you/Vault"
      }
    }
  }
}
No API key. No plugin. No Obsidian open.
LOCAL ONLY MIT LICENSE PYTHON
Installation

Up in three steps.

No plugin to install. No API key. No account. No Obsidian running.

01

Clone the repo

Pull the source from GitHub.

git clone https://github.com/dot-RealityTest/obsidian-codex-mcp copy
02

Install dependencies

Minimal Python setup. Standard tooling.

cd obsidian-codex-mcp && python3 -m venv .venv && .venv/bin/python -m pip install -r requirements.txt copy
03

Add to your MCP client config

Set OBSIDIAN_VAULT_PATH to your vault directory. Drop the block into your client's mcpServers config. Restart client.

OBSIDIAN_VAULT_PATH=/path/to/your/vault .venv/bin/python server.py copy
Compatibility

Works with local MCP clients

If a client can launch a local MCP server, it can use obsidian-codex-mcp. The protocol is open; the list keeps growing.

Codex
OpenAI CLI
Tested
Claude Desktop
Anthropic
Tested
Cline
VS Code agent
Tested
Cursor
IDE agent
Tested
Any MCP client
Open protocol
Compatible

"Local-first isn't a feature.
It's a stance."

Most AI tools route your private notes through remote servers, third-party APIs, and opaque pipelines. obsidian-codex-mcp exists because that doesn't have to be the default.

local-first plugin-free no api key no cloud no obsidian running model agnostic MIT license open source filesystem direct

Ready to give your agent vault access?

Three commands. Zero compromise.

View on GitHub Quick install