让你的 AI 智能体拥有对 Obsidian 库的读写权限。
你的智能体可以通过 Team Relay API 读取笔记、创建新笔记并保持同步。
适用于 Claude Code、Codex CLI、OpenCode 以及任何兼容 MCP 的客户端。
选项 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 .使用你的 Relay 凭据将 MCP 服务器添加到工具配置中。
添加到项目根目录下的 .mcp.json 或 ~/.claude/.mcp.json：
{
"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.json：
{
"mcp_servers": {
"evc-relay": {
"type": "stdio",
"command": "uvx",
"args": ["evc-team-relay-mcp"],
"env": {
"RELAY_CP_URL": "https://cp.yourdomain.com",
"RELAY_EMAIL": "agent@yourdomain.com",
"RELAY_PASSWORD": "your-password"
}
}
}
}添加到 opencode.json：
{
"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"
}
}
}
}如果你是从源码安装而非 PyPI，请将 "command": "uvx" / "args": ["evc-team-relay-mcp"] 替换为：
"command": "uv",
"args": ["run", "--directory", "/path/to/evc-team-relay-mcp", "relay_mcp.py"]可直接复制的配置模板也位于 config/ 目录下。
你的 AI 智能体现在拥有以下工具：
工具 | 描述 |
| 使用凭据进行身份验证（自动管理） |
| 列出可访问的共享（按类型、所有权过滤） |
| 列出文件夹共享中的文件 |
| 从文件夹共享中按路径读取文件 |
| 按 doc_id 读取文档（底层） |
| 按路径创建或更新文件 |
| 按 doc_id 写入文档 |
| 从文件夹共享中删除文件 |
典型工作流： list_shares -> list_files -> read_file / upsert_file
身份验证是自动的 — 服务器会在内部登录并刷新令牌。
Related MCP server: Obsidian Knowledge Management MCP Server
对于共享或服务器端部署，请作为 HTTP 服务器运行：
# Direct
uv run relay_mcp.py --transport http --port 8888
# Docker
RELAY_CP_URL=https://cp.yourdomain.com \
RELAY_EMAIL=agent@yourdomain.com \
RELAY_PASSWORD=your-password \
docker compose up -d然后配置你的 MCP 客户端通过 HTTP 连接：
{
"mcpServers": {
"evc-relay": {
"type": "streamable-http",
"url": "http://your-server:8888/mcp"
}
}
}与基于 shell 的集成相比，该 MCP 服务器提供了显著的安全优势：
无 shell 执行 — 所有操作都是通过 JSON-RPC 进行的 Python 函数调用，消除了命令注入风险
无 CLI 参数 — 凭据和令牌绝不会作为进程参数传递（在 ps 输出中不可见）
自动令牌管理 — 服务器在内部处理登录、JWT 刷新和令牌生命周期；智能体从不接触原始令牌
类型化输入 — 所有参数在执行前都会根据 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 客户端。智能体所做的更改会立即出现在 Obsidian 中，反之亦然。
Python 3.10+，配合 uv（推荐）或 pip
正在运行的 EVC Team Relay 实例（自托管或 托管）
Relay 控制平面上的用户账户
产品 | 功能 | 链接 |
Team Relay | 自托管协作服务器 | |
Team Relay Plugin | Team Relay 的 Obsidian 插件 | |
Relay MCP | AI 智能体的 MCP 服务器 | 本仓库 |
OpenClaw Skill | OpenClaw 智能体技能 (bash) | |
Local Sync | 库 <-> AI 开发工具同步 | |
Spark MCP | AI 工作流目录的 MCP 服务器 |
MIT
Authenticate with the Relay Control Plane.
Uses RELAY_EMAIL and RELAY_PASSWORD env vars. Returns a status message. The token is managed internally — subsequent tool calls use it automatically.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that authentication uses env vars, returns a status message, and that the token is managed automatically for subsequent calls. This covers key behavioral traits without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose. Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema (though not shown), the description sufficiently explains authentication flow, environment variable usage, and automatic token management. It is complete for a simple auth tool with no siblings in the same domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so baseline is 4. The description adds value by explaining that environment variables are used, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Authenticate with the Relay Control Plane', specifying the verb and resource. It is distinct from sibling tools that all perform file or document operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the use of environment variables (RELAY_EMAIL, RELAY_PASSWORD) and notes that the token is managed internally, implying it should be called first. No explicit exclusions or alternatives are needed given no sibling auth tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a file from a folder share.
Removes the file from the folder's metadata registry. The file disappears from Obsidian on next sync.
Args: share_id: UUID of the folder share. file_path: File path within the folder (e.g. "old-note.md").
Returns: JSON with path and status.
| Name | Required | Description | Default |
|---|---|---|---|
| share_id | Yes | ||
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly states the destructive nature ('Delete'), the effect on metadata registry, and the sync behavior with Obsidian. It also mentions the return format. However, it does not cover permanence or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a front-loaded summary. Every sentence provides value: one-line purpose, two behavioral lines, and a structured Args section. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, behavior, parameters, and return value. Given the simplicity of the tool (delete a file), it is nearly complete. Minor missing details like error handling do not detract significantly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully explains both parameters: share_id as UUID and file_path with an example. This adds significant meaning beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear verb and resource: 'Delete a file from a folder share.' It distinguishes from siblings like read_document and upsert_file by specifying deletion and metadata removal. Additional context about Obsidian sync further clarifies the tool's effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to delete a file), but does not explicitly state when not to use or mention alternatives among siblings. No prerequisites or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files in a folder share.
Args: share_id: UUID of the folder share.
Returns: JSON with doc_id and files map (path -> {doc_id, type}).
| Name | Required | Description | Default |
|---|---|---|---|
| share_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It only mentions listing files, not whether it's read-only, requires auth, or any side effects. Incomplete for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one-sentence purpose, Args/Returns format. Every sentence is informative with no redundancy. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (though not detailed), the description adequately covers return structure. Simple tool with one param, but missing error conditions or usage notes. Overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the sole parameter share_id by calling it a 'UUID of the folder share', which the schema (0% coverage) lacked. Effectively clarifies the parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists files in a folder share, distinguishing it from siblings like list_shares (shares list) and read_file (single file). It specifies the argument and return structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives. The required parameter hint is implicit but not enough; lacks context like needing a share_id from list_shares.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read document content by doc_id (low-level).
For doc shares, omit doc_id — it defaults to share_id. For folder shares, pass the file's doc_id from list_files. Prefer read_file for folder shares.
Args: share_id: UUID of the share (for ACL check). doc_id: Document UUID. Defaults to share_id for doc shares. key: Yjs shared type key. Default "contents".
Returns: JSON with doc_id, content, format.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | contents | |
| doc_id | No | ||
| share_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior like defaulting doc_id to share_id for doc shares, and returns JSON with specific fields. No annotations exist, so description carries burden. Could be more explicit about read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a summary line, usage cases, and an Args section. It is informative but slightly long; could be more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists and sibling tools are listed, the description covers all necessary context: parameters, defaults, and when to use alternatives. It is complete for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds substantial meaning beyond the input schema: explains share_id as UUID for ACL check, doc_id defaults, and key as Yjs shared type key. For 0% schema coverage, this fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads document content by doc_id and is low-level. It differentiates from sibling tools like read_file by specifying when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidelines: for doc shares omit doc_id, for folder shares pass doc_id from list_files, and prefers read_file for folder shares. Also clarifies defaults and arguments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file from a folder share by its path.
Resolves path -> doc_id automatically. This is the recommended way to read files from folder shares.
Args: share_id: UUID of the folder share. file_path: File path within the folder (e.g. "Marketing/plan.md").
Returns: JSON with doc_id, content, format, path.
| Name | Required | Description | Default |
|---|---|---|---|
| share_id | Yes | ||
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool resolves path to doc_id automatically, which is a behavioral trait. However, with no annotations provided, it fails to mention whether the operation is read-only, any authorization requirements, error behavior, or side effects. The read operation is implied but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a brief statement of purpose, a key behavioral note, and clear parameter and return explanations. Every sentence adds value, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema (though not shown), the description covers the main functionality, return fields, and paths. It could mention edge cases like missing files or path formats, but overall it's sufficiently complete for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for parameters. The description compensates by explaining share_id as UUID and file_path with an example (e.g., 'Marketing/plan.md'). This adds significant meaning beyond the bare schema, though no validation details are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reads a file from a folder share using a path. It specifies the resource ('folder share') and verb ('Read'), and differentiates from siblings like list_files and read_document by being the recommended method for reading files from folder shares.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'This is the recommended way to read files from folder shares,' implying it's preferred over alternatives, but it does not explicitly state when to avoid this tool or mention specific alternatives like read_document. More explicit guidance would be beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a file in a folder share.
Automatically detects whether the file exists:
Existing file -> updates content (PUT)
New file -> creates file and registers in folder metadata (POST)
This is the recommended way to write files to folder shares.
Args: share_id: UUID of the folder share. file_path: File path within the folder (e.g. "notes/todo.md"). content: Full text content to write.
Returns: JSON with doc_id, path, length, operation ("created" or "updated").
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| share_id | Yes | ||
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the PUT/POST behavior and the returned operation field. It does not mention side effects, error conditions, or permission requirements, which is acceptable for a straightforward file write but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary line, a bullet list of arguments, and a return statement. It is concise and front-loaded. One could slightly tighten the bullet list, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description's brief return explanation suffices. All 3 required parameters are explained, and the behavior is clear. It is complete enough for a tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides clear, semantic explanations for all three parameters (share_id as UUID, file_path as path, content as text) beyond the schema titles. Since schema coverage is 0%, the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create or update a file') and resource ('in a folder share'). It distinguishes itself from siblings like delete_file, read_file, and write_document by being the recommended write tool. The verb-resource combination is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the tool automatically detects file existence and uses PUT/POST accordingly. It marks itself as 'the recommended way to write files to folder shares,' providing clear context. However, it does not explicitly state when to use alternatives like write_document, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write content to a document by doc_id (doc shares only).
For folder shares, use upsert_file instead.
Args: share_id: UUID of the share (for ACL check). doc_id: Document UUID. content: Full text content to write (replaces entire document). key: Yjs shared type key. Default "contents".
Returns: JSON with doc_id, length.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | contents | |
| doc_id | Yes | ||
| content | Yes | ||
| share_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description reveals key behavior: 'replaces entire document', mentions ACL check via share_id. Could specify if document must exist, but sufficient for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences plus bullet-like arg list. No wasted words, well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core usage, parameter roles, and return format. Missing edge cases like non-existent doc, but adequate for a simple write tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; description adds meaning for all parameters: share_id for ACL, doc_id as UUID, content as full text, key default. Also explains return fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Write content to a document' with specific resource (doc_id) and scope ('doc shares only'), distinguishing it from sibling upsert_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (doc shares) and when not ('For folder shares, use upsert_file instead'), providing a clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0authenticatedelete_filelist_fileslist_sharesread_documentread_fileupsert_filewrite_documentScored across 8 tools
Each tool has a clearly distinct purpose: authentication, managing shares, listing files, reading/writing via path or doc_id, and deleting files. No two tools overlap in functionality.
All tools follow a consistent verb_noun snake_case pattern (e.g., list_files, upsert_file, read_document). There are no deviations or mixed conventions.
With 8 tools, the set is well-scoped for managing files within shares. Each tool serves a specific operation, and the count is suitable for the domain without being excessive or insufficient.
The tool surface covers all core operations: authentication, listing shares and files, reading, writing (create/update), and deleting files. There are no obvious gaps for the intended purpose of managing files in folder and doc shares.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…