用途
EVC Team Relay MCP Server（仓库名 evc-team-relay-mcp）用于让 AI 智能体获得对 Obsidian 笔记库的读写访问能力：智能体可以读取已有笔记、创建新笔记，并通过 Team Relay 与 Obsidian 保持同步。它适用于 Claude Code、Codex CLI、OpenCode 以及任何兼容 MCP 的客户端。
主要能力
作为 MCP 服务器，它把 Team Relay 的 REST API 封装为标准 MCP 工具。典型工作流为：list_shares -> list_files -> read_file / upsert_file。认证是自动的——服务器内部完成登录并刷新令牌。
提供的工具包括：list_files、read_file、tr_search、upsert_file。
工具可用性存在两种相互独立的情况：
- 写入（upsert_file）仅限 agent key 模式，这是既定策略：upsert_file 是唯一具备可用后端路由的写入工具，且只有在配置了 agent key（RELAY_AGENT_KEY / RELAY_AGENT_KEYS）时才会写入。JWT 模式调用 upsert_file 会抛出明确的 ValueError 并提示改用 agent-key 模式，而不是令人困惑的 404。
- read_document、write_document 和 delete_file 属于另一项独立的缺失：控制面完全没有为它们提供后端路由，在 agent key 模式下也是如此。切换到 agent key 也不会让它们工作：doc-share 的实时内容仅支持 CRDT/WebSocket（没有 REST 桥接），且服务端尚无按文件删除的 DELETE 路由。若未来添加了这些路由，它们仍会遵循上述“仅 agent key 写入”的策略——JWT 仍将保持只读。
使用方式
提供两种安装方式。 方式 A——来自 PyPI（推荐）：无需安装，uvx 会自动下载并运行，可直接跳到第 2 步配置。 方式 B——从源码安装。
配置：将 MCP 服务器添加到工具的配置中，选择一种认证方式：
- Agent key（推荐）——在 Obsidian 插件的 Team Relay 设置中创建密钥（Agent Keys）。支持读写：list_files、read_file、tr_search 和 upsert_file 都能用单个密钥工作。
- Email + password——在 Relay 实例上使用专用的 agent 账号。
将配置添加到项目根目录的 .mcp.json，或 ~/.claude/.mcp.json；Codex 则添加到 codex.json；OpenCode 添加到 opencode.json。若从源码安装而非 PyPI，请把 "command": "uvx" / "args": ["evc-team-relay-mcp"] 替换为对应源码方式。环境变量说明见仓库。可直接复制的配置模板也放在 config/ 目录中。
远程部署（HTTP 传输）
用于共享或服务端部署时，可作为 HTTP 服务器运行。默认服务器绑定到 127.0.0.1（仅本机），即使主机有公网 IP，端点也无法从网络访问——这符合单机同机运行的常见情况。随后配置 MCP 客户端通过 HTTP 连接。
通过 SSH 隧道远程访问（推荐）：如果 MCP 客户端与服务器不在同一台机器上，请隧道连接到绑定在本机的端口，而不是将其公开暴露。然后把客户端配置指向 http://127.0.0.1:8888/mcp，流量走 SSH 隧道，服务器绑定地址无需更改。
公开 / 反向代理绑定（需显式选择）：如果确实需要服务器直接接受其他主机的连接（例如位于终止 TLS 并处理认证的反向代理之后），请显式传入 --host。务必在反向代理或防火墙之后进行——MCP HTTP 端点自身没有内置认证，在开放网络上绑定到 0.0.0.0 会把每个 relay 工具调用暴露给任何能访问该端口的人。
安全性
相较基于 shell 的集成，MCP 服务器具有明显安全优势：
- 无 shell 执行——所有操作都是通过 JSON-RPC 进行的 Python 函数调用，消除命令注入风险。
- 无命令行参数——凭据和令牌从不作为进程参数传递（在 ps 输出中不可见）。
- 自动令牌管理——服务器内部处理登录、JWT 刷新和令牌生命周期；智能体从不接触原始令牌。
- 类型化输入——所有参数在执行前都会根据 JSON Schema 校验。
- 单一常驻进程——没有每次调用都启动 shell，也没有调用之间的环境泄漏。
注意：如果你正在使用 OpenClaw 技能（bash 脚本），可考虑迁移到该 MCP 服务器，以获得更安全、更易维护的集成。
技术背景与前提
MCP 服务器将 Team Relay 的 REST API 包装为标准的 MCP 工具。Team Relay 将文档存储为 Yjs CRDT，并实时同步到 Obsidian 客户端。智能体所做的更改会立即出现在 Obsidian 中，反之亦然。
运行前提：Python 3.10+，并安装 uv（推荐）或 pip；一个正在运行的 EVC Team Relay 实例（自托管或托管版）；Relay 控制面上的一个用户账号。
该项目是 Entire VC Toolbox 的一部分。
