evc-team-relay-mcp 1.0.4

MCP server for reading and writing Obsidian vault documents via EVC Team Relay

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": "[e-mail]",
        "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:

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

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

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

---

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=[e-mail] \
RELAY_PASSWORD=your-password \
docker compose up -d

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

Then configure your MCP client to connect via HTTP:

{
  "mcpServers": {
    "evc-relay": {
      "type": "streamable-http",
      "url": "http://your-server:8888/mcp"
    }
  }
}

---

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 Plugin	Obsidian plugin for Team Relay	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

• entire.vc
• Discussions
• [e-mail]

License

MIT