Robert Johansson

Posted on May 24

Wiring Claude Code to Your Obsidian Vault via MCP

#mcp #ai #claude #devtools

Every time you start a new Claude Code session, you start from zero. Your agent reads the files you point it to — and nothing else. If your project notes, ADRs, and task lists live in Obsidian, your agent has no idea they exist.

This tutorial wires Claude Code directly to your Obsidian vault. After setup, your agent can read your existing notes, create new ones, and write session summaries that persist between runs — all without you copying anything manually.

How it works

Team Relay is a self-hosted server that syncs your Obsidian vault in real-time via Yjs CRDTs. The evc-team-relay-mcp package wraps its REST API as MCP tools — so any MCP-compatible agent (Claude Code, Codex CLI, OpenCode) can call read_file and upsert_file on your vault.

Claude Code - MCP ->  evc-team-relay-mcp - REST -> Team Relay - Yjs -> Obsidian

Changes appear in Obsidian instantly. Notes you create from Claude appear in your sidebar within seconds.

Step 1 — Run the Team Relay backend

Option A: self-hosted (Docker)

git clone https://github.com/entire-vc/evc-team-relay.git
cd evc-team-relay
cp .env.example .env        # edit: set RELAY_SECRET, DB path, etc.
docker compose up -d

The control plane runs on port 8888 by default. Create a user account via the web UI at http://localhost:8888.

Option B: hosted

If you'd rather skip ops, a hosted instance is available at entire.vc. Create an account there and skip the Docker step. Either way, you'll end up with a control-plane URL, email, and password — that's all the MCP server needs.

Step 2 — Share your vault folder

In Obsidian, open the Team Relay plugin settings and create a folder share for the vault folder you want the agent to access. Copy the share ID — you'll need it in a moment.

If you haven't installed the Obsidian plugin yet: evc-team-relay-obsidian-plugin

Step 3 — Configure Claude Code

Create or edit .mcp.json in your project root (or ~/.claude/.mcp.json for global access):

{
  "mcpServers": {
    "evc-relay": {
      "command": "uvx",
      "args": ["evc-team-relay-mcp"],
      "env": {
        "RELAY_CP_URL": "https://cp.yourdomain.com",
        "RELAY_EMAIL": "your@email.com",
        "RELAY_PASSWORD": "your-password"
      }
    }
  }
}

No install step needed — uvx pulls the package from PyPI on first run. Restart Claude Code and the evc-relay tools will appear.

Step 4 — Try it

Here are three prompts that demonstrate the agent working with your vault. Replace <share_id> with the UUID from Step 2.

Prompt 1: discover what's in the vault

List the files in my Obsidian share <share_id> and tell me which ones look like project notes or task lists.

Claude calls list_shares, then list_files, and returns a summary of your vault structure. It does not read any content yet — just the
file tree.

Prompt 2: read existing context

Read "Projects/active-sprint.md" from share <share_id> and summarize what's in progress.

Claude calls read_file with file_path="Projects/active-sprint.md"
and returns a summary. The file content is pulled live from your vault — if you edited it in Obsidian five seconds ago, the agent sees the latest version.

Prompt 3: write a session summary

Based on what we've done this session, create a session log at "AI-sessions/2026-05-15.md" in share <share_id>. Include: what we changed, any open questions, and next steps.

Claude calls upsert_file. If the file doesn't exist, it creates it. If it does, it updates in place. Open Obsidian — the note appears in your sidebar within a few seconds.

Tools reference

Tool	What it does
`authenticate`	Logs in and manages JWT tokens internally (auto-called)
`list_shares`	Lists accessible shares; filter by `kind="folder"`
or `kind="doc"`
`list_files`	Returns the file tree of a folder share
`read_file`	Reads a file by path from a folder share
`upsert_file`	Creates or updates a file by path
`read_document`	Low-level: reads by doc_id (for doc shares)
`write_document`	Low-level: writes by doc_id
`delete_file`	Deletes a file from a folder share

The typical flow is: list_shares → list_files → read_file /
upsert_file. Authentication is automatic — you never pass tokens to
the agent manually.

A few things worth knowing

Nothing is shell-executed. All operations are Python function calls over JSON-RPC. Credentials are env vars, never CLI arguments. There is no command injection surface.

The agent doesn't see your whole vault by default. It only accesses shares you explicitly create. You can share one folder per project and keep the rest private.

Works with other MCP clients too. The same .mcp.json config works for Codex CLI and OpenCode. The session-summary workflow is identical.

Try it

MCP server repo (MIT): github.com/entire-vc/evc-team-relay-mcp
Team Relay backend (MIT): github.com/entire-vc/evc-team-relay

If something breaks or a tool behaves unexpectedly, open an issue on the MCP repo. Feedback on the tool API is especially welcome — we're still shaping which operations are most useful for AI agent workflows.

DEV Community