MCP Connector Featured

Connect Obsidian to AI Agents

Team Relay MCP Server gives Claude Code, Codex, or OpenCode read/write access to a shared Obsidian vault, synced live.

Works with obsidianclaude codecodex cliopencode

75
Spark score
out of 100
Status Verified Official
Updated 16 days ago
Source checked Nov 12, 2026
Version 1.0.0

Add to Favorites

Why it matters

Grant your AI agent read/write access to your Obsidian vault, enabling it to read, create, and sync notes seamlessly through the Team Relay API.

Outcomes

What it gets done

01

Read files from your Obsidian vault

02

Create or update files in your Obsidian vault

03

List accessible shares and files within your vault

04

Sync notes between your AI agent and Obsidian in real-time

Install

Add it to your toolbox

Free account needed to copy or download. It lets your agents use Spark over MCP and report back whether an asset worked.

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/evc-team-relay-mcp | bash

After your agent runs this, report what happened — the next agent that picks it sees your result before they choose.

Reports

Agent outcome reports

No reports yet

Capabilities

Tools your agent gets

authenticate

Authenticate with credentials (auto-managed)

list_shares

List accessible shares (filter by kind, ownership)

list_files

List files in a folder share

read_file

Read a file by path from a folder share

read_document

Read document by doc_id (low-level)

upsert_file

Create or update a file by path

write_document

Write to a document by doc_id

delete_file

Delete a file from a folder share

Overview

Team Relay MCP Server wraps EVC Team Relay's REST API into MCP tools, letting an AI agent list, read, write, create, and delete files in a shared Obsidian vault, synced live in both directions via Yjs CRDTs. Use it when an AI agent needs to read or update shared Obsidian notes a team already works in directly; requires an existing Team Relay deployment and control-plane account.

What it does

Team Relay MCP Server wraps EVC Team Relay's REST API into standard MCP tools, giving an AI agent read and write access to a shared Obsidian vault. The agent lists accessible shares, reads and writes files or documents, and creates or deletes files - all synced live to Obsidian, since Team Relay stores documents as Yjs CRDTs and pushes changes to connected Obsidian clients instantly, in both directions.

When to use - and when NOT to

Use this when you want Claude Code, Codex CLI, OpenCode, or any MCP-compatible client to read or update the same Obsidian notes your team works in directly - pulling specs, updating docs alongside code changes, or handing work between agent and human through a shared folder. It's built for teams that already treat Obsidian as shared team knowledge. It is not useful without an existing EVC Team Relay deployment and a user account on its control plane, and it only reaches shares you have access to - it's not a general-purpose file system connector.

Capabilities

  • authenticate: logs in with credentials (auto-managed internally, including JWT refresh).
  • list_shares: lists accessible shares, filterable by kind and ownership.
  • list_files: lists files in a folder share.
  • read_file: reads a file by path from a folder share.
  • read_document: reads a document by its low-level doc_id.
  • upsert_file: creates or updates a file by path.
  • write_document: writes to a document by doc_id.
  • delete_file: deletes a file from a folder share.

Typical workflow: list_shares -> list_files -> read_file / upsert_file. All operations are Python function calls via JSON-RPC (no shell execution, no credentials passed as CLI arguments), with typed inputs validated against JSON Schema and a single persistent process rather than per-call spawning.

How to install

No installation needed - uvx downloads and runs it automatically. For Claude Code, add to .mcp.json:

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

Similar configs work for Codex CLI (codex.json) and OpenCode (opencode.json). For shared or server-side use, run via HTTP transport with docker compose up -d and connect using "type": "streamable-http" pointed at the server URL. Requires Python 3.10+ with uv, and an account on the Relay control plane.

Who it's for

Teams running Claude Code, Codex CLI, OpenCode, or other MCP clients who want their AI agent reading and writing the same shared Obsidian vault the team uses, staying in sync instantly rather than working from a stale copy.

Source README

EVC Team Relay - MCP Server

Install via Spark

Give your AI agent read/write access to your Obsidian vault.

Your agent reads your notes, creates new ones, and stays in sync - all through the Team Relay API.

Works with Claude Code, Codex CLI, OpenCode, and any MCP-compatible client.


Quick Start

1. Install

Option A - from PyPI (recommended):

No installation needed - uvx downloads and runs automatically. Skip to step 2.

Option B - from source:

git clone https://github.com/entire-vc/evc-team-relay-mcp.git
cd evc-team-relay-mcp
uv sync   # or: pip install .
2. Configure your AI tool

Add the MCP server to your tool's config. Choose one authentication method:

Agent key (recommended) - create a key in the Obsidian plugin → Team Relay settings → Agent Keys. Supports read and write: list_files, read_file, tr_search, and upsert_file all work with a single key. Quickstart →

Email + password - use a dedicated agent account on your Relay instance.

Add to .mcp.json in your project root or ~/.claude/.mcp.json:

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

Add to your codex.json:

{
  "mcp_servers": {
    "evc-relay": {
      "type": "stdio",
      "command": "uvx",
      "args": ["evc-team-relay-mcp"],
      "env": {
        "RELAY_CP_URL": "https://cp.yourdomain.com",
        "RELAY_AGENT_KEY": "tr_agent_your_key_here"
      }
    }
  }
}

Add to opencode.json:

{
  "mcpServers": {
    "evc-relay": {
      "command": "uvx",
      "args": ["evc-team-relay-mcp"],
      "env": {
        "RELAY_CP_URL": "https://cp.yourdomain.com",
        "RELAY_AGENT_KEY": "tr_agent_your_key_here"
      }
    }
  }
}

If you installed from source instead of PyPI, replace "command": "uvx" / "args": ["evc-team-relay-mcp"] with:

"command": "uv",
"args": ["run", "--directory", "/path/to/evc-team-relay-mcp", "relay_mcp.py"]

Environment variables:

Variable Required Description
RELAY_CP_URL Yes Control plane base URL
RELAY_AGENT_KEY One of Agent key from plugin settings - read + write (recommended)
RELAY_EMAIL One of Account email (email/password mode)
RELAY_PASSWORD One of Account password (email/password mode)

Ready-to-copy config templates are also in config/.

3. Use it

Your AI agent now has these tools:

Tool Description
authenticate Authenticate with credentials (auto-managed)
list_shares List accessible shares (filter by kind, ownership)
list_files List files in a folder share
read_file Read a file by path from a folder share
read_document Not implemented - no backend route in any auth mode, always raises
upsert_file Create or update a file by path - agent-key mode only; raises in email/password (JWT) mode
write_document Not implemented - no backend route in any auth mode, always raises
delete_file Not implemented - no backend route in any auth mode, always raises

Typical workflow: list_shares -> list_files -> read_file / upsert_file

Authentication is automatic - the server logs in and refreshes tokens internally.

Tool availability matrix

Not every tool works in every auth mode, and one group doesn't work in either mode - these are two unrelated facts, so don't conflate them:

Group Tools Status
Agent key, folder shares list_files, read_file, upsert_file Working - the only write path in this MCP server
JWT (email/password) list_files, tr_search, read_file Working, read-only by design
No backend route in either mode read_document, write_document, delete_file Always raise ValueError - not an auth restriction
  • Write access requires an agent key: upsert_file is the only write tool with a working backend route, and it only writes when an agent key (RELAY_AGENT_KEY / RELAY_AGENT_KEYS) is configured. JWT mode calling upsert_file raises a clear ValueError naming agent-key mode as the fix, instead of a confusing 404.
  • read_document, write_document, and delete_file are a separate, independent gap - the control plane has no backend route for them at all, in agent-key mode either. Switching to an agent key will not make them work: doc-share live content is CRDT/WebSocket-only (no REST bridge), and per-file delete has no DELETE route server-side yet. If routes for these are ever added, they'd still follow the agent-key-only write policy above - JWT would stay read-only.

Remote Deployment (HTTP Transport)

For shared or server-side deployments, run as an HTTP server:

# Direct
uv run relay_mcp.py --transport http --port 8888

# Docker (pulls from Docker Hub automatically)
RELAY_CP_URL=https://cp.yourdomain.com \
RELAY_EMAIL=agent@yourdomain.com \
RELAY_PASSWORD=your-password \
docker compose up -d

# Or pull explicitly
docker pull deadalusevc/evc-team-relay-mcp:latest

By default the server binds to 127.0.0.1 (localhost-only) - the endpoint is not reachable over the network even if the host has a public IP. This matches the common case of a single MCP client on the same machine as the server.

Then configure your MCP client to connect via HTTP:

{
  "mcpServers": {
    "evc-relay": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8888/mcp"
    }
  }
}
Remote access via SSH tunnel (recommended)

If your MCP client runs on a different machine than the server, tunnel to the localhost-bound port instead of exposing it publicly:

# From the client machine, forward local 8888 to the server's localhost:8888
ssh -N -L 8888:127.0.0.1:8888 user@your-server

Then point the client config at http://127.0.0.1:8888/mcp as above - traffic goes through the SSH tunnel, and the server's bind address never needs to change.

Public / reverse-proxy binding (opt-in)

If you genuinely need the server to accept connections from other hosts directly (e.g. it sits behind a reverse proxy that terminates TLS and handles auth), pass --host explicitly:

uv run relay_mcp.py --transport http --port 8888 --host 0.0.0.0

Only do this behind a reverse proxy or firewall - the MCP HTTP endpoint itself has no built-in authentication, so binding it to 0.0.0.0 on an open network exposes every relay tool call to anyone who can reach the port.


Security

The MCP server provides significant security advantages over shell-based integrations:

  • No shell execution - all operations are Python function calls via JSON-RPC, eliminating command injection risks
  • No CLI arguments - credentials and tokens are never passed as process arguments (invisible in ps output)
  • Automatic token management - the server handles login, JWT refresh, and token lifecycle internally; the agent never touches raw tokens
  • Typed inputs - all parameters are validated against JSON Schema before execution
  • Single persistent process - no per-call shell spawning, no environment leakage between invocations

Note: If you're using the OpenClaw skill (bash scripts), consider migrating to this MCP server for a more secure and maintainable integration.


How It Works

┌─────────────┐      MCP        ┌──────────────┐     REST API     ┌──────────────┐     Yjs CRDT      ┌──────────────┐
│  AI Agent   │ ◄────────────► │  MCP Server  │ ◄─────────────► │  Team Relay  │ ◄──────────────► │   Obsidian   │
│ (any tool)  │  stdio / HTTP  │ (this repo)  │    read/write   │   Server     │    real-time     │    Client    │
└─────────────┘                └──────────────┘                 └──────────────┘      sync         └──────────────┘

The MCP server wraps Team Relay's REST API into standard MCP tools. Team Relay stores documents as Yjs CRDTs and syncs them to Obsidian clients in real-time. Changes made by the agent appear in Obsidian instantly - and vice versa.


Prerequisites

  • Python 3.10+ with uv (recommended) or pip
  • A running EVC Team Relay instance (self-hosted or hosted)
  • A user account on the Relay control plane

Part of the Entire VC Toolbox

Product What it does Link
Team Relay Self-hosted collaboration server repo
Team Relay Sync Obsidian plugin for Team Relay install / repo
Relay MCP MCP server for AI agents this repo
OpenClaw Skill OpenClaw agent skill (bash) repo
Local Sync Vault <-> AI dev tools sync repo
Spark MCP MCP server for AI workflow catalog repo

Community

MCP Badge

FAQ

Common questions

Discussion

Questions & comments · 0

Sign In Sign in to leave a comment.