evc-team-relay-mcp

Purpose

EVC Team Relay MCP Server (repository name evc-team-relay-mcp) is used to give AI agents read and write access to an Obsidian vault: agents can read existing notes, create new notes, and stay in sync with Obsidian via Team Relay. It works with Claude Code, Codex CLI, OpenCode, and any MCP-compatible client.

Main capabilities

As an MCP server, it wraps the Team Relay REST API as standard MCP tools. A typical workflow is: list_shares -> list_files -> read_file / upsert_file. Authentication is automatic—the server handles login and token refresh internally.

The tools provided include: list_files, read_file, tr_search, upsert_file.

There are two independent situations regarding tool availability:

• Writing (upsert_file) is limited to agent key mode only; this is by established policy: upsert_file is the only write tool with an available backend route, and it only writes when an agent key is configured (RELAY_AGENT_KEY / RELAY_AGENT_KEYS). Calling upsert_file in JWT mode throws an explicit ValueError and prompts you to switch to agent-key mode, rather than a confusing 404.
• read_document, write_document, and delete_file are a separate missing piece: the control plane provides no backend routes for them at all, even in agent key mode. Switching to an agent key will not make them work either: doc-share live content only supports CRDT/WebSocket (there is no REST bridge), and the server does not yet have a per-file DELETE route. If these routes are added in the future, they will still follow the above "agent key writes only" policy—JWT will remain read-only.

Usage

Two installation methods are provided. Method A—from PyPI (recommended): no installation needed; uvx will automatically download and run it, and you can go directlyto step 2 for configuration. Method B—install from source.

Configuration: add the MCP server to your tool's configuration and choose an authentication method:

• Agent key (recommended)—create a key in the Team Relay settings of the Obsidian plugin (Agent Keys). Read and write are supported: list_files, read_file, tr_search, and upsert_file all work with a single key.
• Email + password—use a dedicated agent account on the Relay instance.

Add the configuration to .mcp.json in the project root, or to ~/.claude/.mcp.json; for Codex, add it to codex.json; for OpenCode, add it to opencode.json. If installing from source rather than PyPI, replace "command": "uvx" / "args": ["evc-team-relay-mcp"] with the corresponding source-based approach. See the repository for environment variable descriptions. Configuration templates you can copy directly are also in the config/ directory.

Remote deployment (HTTP transport)

For shared or server-side deployments, it can run as an HTTP server. By default the server binds to 127.0.0.1 (local machine only), so even if the host has a public IP, the endpoint cannot be accessed from the network—this matches the common case of running on the same machine. Then configure the MCP client to connect over HTTP.

Remote access via SSH tunnel (recommended): if the MCP client and server are not on the same machine, tunnel to the port bound to the local machine instead of exposing it publicly. Then point the client configuration to http://127.0.0.1:8888/mcp，流量走 For SSH tunnels, the server bind address does not need to be changed.

Public / reverse proxy binding (must be explicitly selected): If the server really needs to accept connections directly from other hosts (for example, behind a reverse proxy that terminates TLS and handles authentication), explicitly pass --host. Be sure to do this behind a reverse proxy or firewall—the MCP HTTP endpoint itself has no built-in authentication, and binding to 0.0.0.0 on an open network will expose every relay tool call to anyone who can access that port.

Security

Compared with shell-based integrations, the MCP server has clear security advantages:

• No shell execution—all operations are Python function calls made through JSON-RPC, eliminating the risk of command injection.
• No command-line 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; agents never touch raw tokens.
• Typed input—all parameters are validated against JSON Schema before execution.
• A single long-running process—no shell is started for each call, and there is no environment leakage between calls.

Note: If you are using an OpenClaw skill (bash script), consider migrating to this MCP server for a safer and more maintainable integration.

Technical Background and Prerequisites

The MCP server wraps Team Relay's REST API as standard MCP tools. Team Relay stores documents as Yjs CRDTs and synchronizes them to Obsidian clients in real time. Changes made by agents appear immediately in Obsidian, and vice versa.

Prerequisites: Python 3.10+, with uv (recommended) or pip installed; a running EVC Team Relay instance (self-hosted or hosted); a user account on the Relay control plane.

This project is part of the Entire VC Toolbox.