EVC Team Relay MCP

EVC Team Relay - MCP サーバー

AI エージェントに Obsidian の保管庫への読み書きアクセスを許可します。

エージェントはノートを読み取り、新しいノートを作成し、常に同期された状態を保ちます。すべて 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 サーバーをツールの設定に追加します。認証方法を 1 つ選択してください。

エージェントキー（推奨）— Obsidian プラグイン → Team Relay の設定 → Agent Keys でキーを作成します。読み取りと書き込みに対応しており、list_files、read_file、tr_search、upsert_file のすべてを 1 つのキーで利用できます。クイックスタート →

メールアドレス + パスワード — Relay インスタンスでエージェント専用アカウントを使用します。

{
  "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 エージェントで次のツールを使用できるようになります。

一般的なワークフロー： list_shares -> list_files -> read_file / upsert_file

認証は自動で行われます。サーバーが内部でログインし、トークンを更新します。

ツールの利用可否マトリックス

すべてのツールがすべての認証モードで動作するわけではありません。また、どちらのモードでも動作しないグループが1つあります。これは互いに無関係な事実なので、混同しないでください。

• 書き込みアクセスは、承認済みのポリシーによりエージェントキー専用です（TR-05（内部実装記録）を参照）： upsert_file は、動作するバックエンドルートを持つ唯一の書き込みツールであり、エージェントキー（RELAY_AGENT_KEY / RELAY_AGENT_KEYS）が設定されている場合にのみ書き込みます。JWT モードで upsert_file を呼び出すと、分かりにくい404ではなく、エージェントキーモードへの切り替えを明示する ValueError が発生します。
• read_document、write_document、delete_file は、これとは別の独立した未対応項目です — エージェントキーモードであっても、コントロールプレーンにはこれらのバックエンドルートがまったくありません。エージェントキーに切り替えても、これらのツールは動作しません。ドキュメント共有のライブコンテンツは CRDT/WebSocket のみで扱われ（REST ブリッジはありません）、ファイル単位の削除にはサーバー側の DELETE ルートがまだありません。これらのルートが今後追加された場合も、上記のエージェントキー専用の書き込みポリシーが適用され、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 クライアントを使う一般的なケースに適しています。

次に、HTTP 経由で接続するよう MCP クライアントを設定します。

{
  "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 にバインドすると、ポートに到達できるすべての人に、あらゆるリレーのツール呼び出しが公開されます。

セキュリティ

MCP サーバーには、シェルベースの統合と比べて、セキュリティ上の大きな利点があります。

• シェルを実行しません — すべての操作は JSON-RPC 経由の Python 関数呼び出しで行われるため、コマンドインジェクションのリスクを排除できます
• CLI 引数を使いません — 認証情報やトークンがプロセス引数として渡されることはなく、ps の出力にも表示されません
• トークンを自動管理します — サーバーがログイン、JWT の更新、トークンのライフサイクルを内部で処理するため、エージェントが生のトークンを扱うことはありません
• 型付き入力 — 実行前に、すべてのパラメーターが JSON Schema に照らして検証されます
• 単一の常駐プロセス — 呼び出しごとのシェル起動がなく、呼び出し間で環境が漏えいすることもありません

注： 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 に即座に反映され、その逆も同様です。

前提条件

• uv（推奨）または pip を使用できる Python 3.10 以降
• 稼働中の EVC Team Relay インスタンス（セルフホストまたはホスト版）
• Relay のコントロールプレーンのユーザーアカウント

Entire VC ツールボックスの一部

コミュニティ

• entire.vc
• ディスカッション
• [email protected]
• ヘルプの入手方法と期待できる内容

ライセンス

MIT