Evc Team Relay MCP

EVC Team Relay - MCP Server

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.

Claude Code — agent key

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" } } } }

Claude Code — email/password

{

"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" } } } }

Codex CLI

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" } } } }

OpenCode

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" } } } }

From source (all tools)

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:

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

3. Use it

Your AI agent now has these tools:

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:

• 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

Community

• entire.vc
• Discussions

-

• Where to get help and what to expect

Find us in other directories

License

MIT