EVC Team Relay MCP

EVC Team Relay - MCP 服务

为你的 AI Agent 提供 Obsidian 库的读写权限。

你的 Agent 可以读取笔记、创建新笔记并保持同步——这一切都通过 Team Relay API 完成。

兼容 Claude Code、Codex CLI、OpenCode 以及任何兼容 MCP 的客户端。

快速开始

1. 安装

选项 A — 从 PyPI 安装（推荐）：

无需安装——uvx 会自动下载并运行。请跳至第 2 步。

选项 B — 从源代码安装：

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

2. 配置 AI 工具

将 MCP 服务添加到工具的配置中。选择一种身份验证方式：

Agent 密钥（推荐）——在 Obsidian 插件 → Team Relay 设置 → Agent Keys 中创建密钥。支持读取和写入：list_files、read_file、tr_search 和 upsert_file 均可使用同一个密钥。 快速入门 →

邮箱 + 密码——在你的 Relay 实例上使用专用 Agent 账号。

{
  "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": "[email protected]",
        "RELAY_PASSWORD": "your-password"
      }
    }
  }
}

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

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

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

环境变量：

config/ 中也提供了可直接复制的配置模板。

3. 使用

你的 AI Agent 现在可以使用以下工具：

典型工作流： list_shares -> list_files -> read_file / upsert_file

身份验证会自动完成——服务会在内部登录并刷新令牌。

工具可用性矩阵

并非所有工具都能在每种认证模式下使用；还有一组工具在两种模式下都无法使用——这是两个互不相关的事实，请勿混为一谈：

• 根据正式政策，写入权限仅限 Agent 密钥模式（参见 TR-05（内部实现记录））： upsert_file 是唯一具有可用后端路由的写入工具，且只有在配置了 Agent 密钥（RELAY_AGENT_KEY / RELAY_AGENT_KEYS）时才会写入。JWT 模式下调用 upsert_file 会抛出明确的 ValueError，指出应切换到 Agent 密钥模式，而不是令人困惑的 404。
• read_document、write_document 和 delete_file 是另一个独立的问题——控制平面完全没有这些工具的后端路由，Agent 密钥模式下也一样。切换到 Agent 密钥不会让它们生效：文档共享的实时内容仅支持 CRDT/WebSocket（没有 REST 桥接），而服务端目前也没有针对单个文件的 DELETE 路由。如果将来添加了这些路由，写入仍会遵循上述仅限 Agent 密钥的政策——JWT 仍将保持只读。

远程部署（HTTP 传输）

对于共享或服务端部署，请以 HTTP 服务的方式运行：

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

# Docker (pulls from Docker Hub automatically)
RELAY_CP_URL=https://cp.yourdomain.com \
[email protected] \
RELAY_PASSWORD=your-password \
docker compose up -d

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

默认情况下，服务绑定到 127.0.0.1（仅限本地主机）——即使主机拥有公网 IP，也无法通过网络访问此端点。这适用于常见场景：MCP 客户端与服务运行在同一台机器上。

然后配置 MCP 客户端通过 HTTP 连接：

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

通过 SSH 隧道远程访问（推荐）

如果 MCP 客户端和服务运行在不同机器上，请将流量隧道转发到绑定本地主机的端口，而不是将其公开到公网：

# 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

然后像上面那样，将客户端配置指向 http://127.0.0.1:8888/mcp——流量会通过 SSH 隧道传输，因此无需更改服务的绑定地址。

公网／反向代理绑定（可选）

如果确实需要服务直接接受来自其他主机的连接（例如，服务位于负责终止 TLS 并处理认证的反向代理之后），请显式传入 --host：

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

仅在反向代理或防火墙之后这样做——MCP HTTP 端点本身没有内置认证，因此在开放网络上将其绑定到 0.0.0.0 会让任何能访问该端口的人都能调用所有 Relay 工具。

安全性

与基于 shell 的集成相比，MCP 服务具有显著的安全优势：

• 不执行 shell——所有操作都是通过 JSON-RPC 调用 Python 函数，可消除命令注入风险
• 不传递 CLI 参数——凭据和令牌绝不会作为进程参数传递（在 ps 输出中不可见）
• 自动管理令牌——服务在内部处理登录、JWT 刷新和令牌生命周期；Agent 不会接触原始令牌
• 类型化输入——执行前会根据 JSON Schema 验证所有参数
• 单个持久进程——无需为每次调用启动 shell，不会在调用之间泄露环境变量

**注意：**如果你正在使用 OpenClaw skill（bash 脚本），可以考虑迁移到此 MCP 服务，以获得更安全、更易维护的集成。

工作原理

┌─────────────┐      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         └──────────────┘

MCP 服务将 Team Relay 的 REST API 封装为标准 MCP 工具。Team Relay 将文档存储为 Yjs CRDT，并实时同步到 Obsidian 客户端。Agent 所做的更改会立即显示在 Obsidian 中，反之亦然。

前置条件

• Python 3.10+，以及 uv（推荐）或 pip
• 正在运行的 EVC Team Relay 实例（可自托管或托管）
• Relay 控制平面上的用户账户

Entire VC 工具箱的一部分

社区

• entire.vc
• 讨论区
• [email protected]
• 如何获取帮助及预期事项

许可证

MIT