ownerwatch

ownerwatch-mcp

Model Context Protocol サーバーです。コーディングエージェントが、あらゆる EVM アドレスについて「このコントラクトを管理しているのは誰ですか？」と回答できるようにします。オーナー、プロキシのアップグレード管理者、ビーコン、Safe（署名者、しきい値、モジュール）、タイムロック（遅延）、AccessControl と AccessManager のロールをたどり、EOA、1-of-N の Safe、タイムロックなしで保持されている権限にフラグを立てます。

ownerwatch を基盤とし、お使いのマシン上で stdio 経由で動作します。すべてのツールは読み取り専用です。キー、ウォレット、アカウントは不要で、オンチェーンに何かが送信されることもありません。

ツール

ツール	返される内容
probe_admin_surface(addresses, chain or rpc_url)	ownerwatch の Markdown レポートと、構造化データを返します。各対象の管理経路、検出事項、読み取られたすべてのノード、not_established（この読み取りでは確認できなかった内容）が含まれます。label、roles_from_logs、logs_rpc_url はオプションです。
check_disclosure(disclosure_json, rpc_url, block?)	ERC-8241 の管理情報開示に対して ownerwatch disclosure check を実行します。1 つの固定ブロックにおける各レコードの正常、一致しない点、検証不能な点に加え、開示から漏れている管理情報を返します。status は discrepancies_found（CLI の終了コード 1）、no_discrepancies、no_discrepancies_some_unverifiable、または nothing_verified です。
suggest_monitoring_config(addresses, chain or rpc_url)	これらのコントラクトと、その上位にあるすべてのコントラクトおよび Safe を監視する ownerwatch YAML 設定を返します。返却前に ownerwatch で読み込み可能なことを確認します。

すべての結果の冒頭には、同じ注意書きが表示されます。これは判定ではなく、チェーン上の状態を示すものです。コントラクトの状態が何を示しているかを説明します。キーがどのように保管されているか（EOA は単一のキー、ハードウェアウォレット、または MPC 構成の場合があります。また、Safe の署名者が 1 人である場合もあります）は示しません。検出事項がないからといって、コントラクトが安全である証明にはなりません。

読み取りに失敗した場合（RPC の停止、レート制限、チェーンの不一致、コードのないアドレス、時間制限の超過）は、結論に至らなかったことを示す MCP エラーが返されます。空または問題なしのレポートが返されることはありません。

スキルとして使用する

skill/ フォルダーには、ポータブルな Agent Skill（SKILL.md）が含まれています。これを Claude Code、Cursor、Copilot、または SKILL.md 標準を読み取る任意のエージェントに追加すると、エージェントは「このコントラクトを管理しているのは誰ですか？」という質問にいつ、どのように回答すべきかを学習します。これらの MCP ツールまたは ownerwatch CLI を操作して回答し、シミュレーションで検出事項を立証します。キー、ウォレット、アカウントは不要です。インストール方法は skill/README.md を参照してください。

クイックスタート

空のディレクトリで、Python 3.10 以降を使用します。

python3 -m venv .venv
.venv/bin/pip install ownerwatch-mcp
.venv/bin/ownerwatch-mcp --version

次に、インストールしたコマンドの絶対パスを使ってクライアントに登録します（Windows の場合は .venv\Scripts\ownerwatch-mcp.exe）。

Claude Code

claude mcp add ownerwatch -- "$PWD/.venv/bin/ownerwatch-mcp"
claude mcp list            # ownerwatch: /…/.venv/bin/ownerwatch-mcp - ✔ Connected

すべてのプロジェクトで使うには --scope user を追加します。プロジェクトの .mcp.json を通じて共有するには --scope project を追加します。

Claude Desktop、Cursor、および mcpServers ファイルを使用するその他のクライアント（claude_desktop_config.json、~/.cursor/mcp.json または .cursor/mcp.json、プロジェクトの .mcp.json）：

{
  "mcpServers": {
    "ownerwatch": {
      "command": "/absolute/path/to/.venv/bin/ownerwatch-mcp"
    }
  }
}

VS Code（.vscode/mcp.json、または MCP: Open User Configuration）：

{
  "servers": {
    "ownerwatch": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/ownerwatch-mcp"
    }
  }
}

Codex（~/.codex/config.toml）：特に指定しない限り、Codex は 60 秒後にツールを停止します。

[mcp_servers.ownerwatch]
command = "/absolute/path/to/.venv/bin/ownerwatch-mcp"
tool_timeout_sec = 300

uv がインストールされていれば、これらはいずれも venv の代わりに "command": "uvx", "args": ["ownerwatch-mcp"] を使用できます。

次に、エージェントに次のように尋ねます。「Ethereum 上の 0x1F98431c8aD98523631AE4a59f267346ea31F984 をアップグレードしたり、制御権を奪ったりできるのは誰ですか？」

クライアントを使わずに試す

同じディレクトリに try.py として保存し、.venv/bin/python try.py を実行します。

import anyio
from mcp import ClientSession, StdioServerParameters, stdio_client

async def main():
    server = StdioServerParameters(command=".venv/bin/ownerwatch-mcp")
    async with stdio_client(server) as (read, write), ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("probe_admin_surface", {
            "addresses": ["0x1F98431c8aD98523631AE4a59f267346ea31F984"], "chain": "ethereum", "label": "Uniswap V3"})
        print(result.content[0].text)

anyio.run(main)

Uniswap V3 Factory のレポートが出力されます。以下は、2026 年 11 月 5 日に実行した結果の抜粋です。

# Uniswap V3 admin surface on ethereum

> **Chain view, not a verdict. Read from ethereum (chain id 1) via https://ethereum-rpc.publicnode.com, head block 26347629 (2026-11-05 09:06 UTC) when the call started. ... It does not show how a key is held ...**

| Address | Type | Controlled by | Detail |
|---|---|---|---|
| `0x1F98…F984` | contract | `0xf237…Bf5A` | - |
| `0xf237…Bf5A` | contract | `0x1a9C…35BC` | - |
| `0x1a9C…35BC` | legacy-timelock | `0x408E…24C3` | 48h delay |
| `0x408E…24C3` | contract | `0x1a9C…35BC` | - |

## Control paths

- 0x1F98…F984 (contract) -> 0xf237…Bf5A (contract) -> 0x1a9C…35BC (legacy-timelock 48h) -> 0x408E…24C3 (contract)

構造化された結果には、JSON として同じ情報が含まれます。targets[].control_path、findings、not_established、nodes です。

チェーンと RPC

公開されているデフォルトの RPC を使うには chain を、自分の RPC を使うには rpc_url を渡します。両方を指定する場合、RPC のチェーン ID は chain と一致している必要があります。ここに記載されていないチェーンでは、rpc_url のみを渡してください。

チェーン	id	デフォルトの RPC
ethereum (eth, mainnet)	1	https://ethereum-rpc.publicnode.com
optimism (op)	10	https://optimism-rpc.publicnode.com
bsc (bnb)	56	https://bsc-rpc.publicnode.com
gnosis	100	https://gnosis-rpc.publicnode.com
polygon (matic, pol)	137	https://polygon-bor-rpc.publicnode.com
base	8453	https://base-rpc.publicnode.com
arbitrum (arb)	42161	https://arb1.arbitrum.io/rpc
avalanche (avax)	43114	https://avalanche-c-chain-rpc.publicnode.com
linea	59144	https://rpc.linea.build
scroll	534352	https://scroll-rpc.publicnode.com

公開 RPC では短時間に大量のリクエストを送ると制限されます。サーバーは制限時間内であればレート制限が解除されるまで待機しますが、大規模なグラフやロールの完全な再生には、自分の RPC のほうが高速です。check_disclosure で古い block を指定するには、アーカイブ RPC が必要です。

設定は、サーバープロセスの環境変数として指定します（クライアント設定では env の下に指定します）。

変数	効果
OWNERWATCH_MCP_TIMEOUT	ツール呼び出しのタイムアウト秒数。10～3600（デフォルトは240）です。超過すると、呼び出しはエラーを返します。
OWNERWATCH_MCP_ALLOW_PRIVATE_RPC=1	http:// およびローカルノードなどのプライベートまたはループバック RPC ホストを許可します。デフォルトでは無効です。エージェントが読んだテキストによって、サーバーがユーザー自身のネットワークに接続されるのを防ぎます。

プライバシー

サーバーは何も保存せず、テレメトリーも行いません。呼び出しに応答する際、以下を送信します。

• アドレスを、読み取り専用の JSON-RPC リクエスト（eth_call、eth_getCode、eth_getStorageAt、eth_getLogs など）として、選択した RPC または上記のデフォルト RPC に送信します。RPC クライアントは読み取り以外のメソッドを拒否します。
• コントラクトアドレスを Sourcify に送信し、ロールの命名とタイムロックの認識に使用する検証済み ABI を取得します。
• roles_from_logs を指定した場合、logs_rpc_url を渡さない限り、コントラクトアドレスを Ethereum、Optimism、Arbitrum、Base、Gnosis、Polygon 上の公開 Tenderly ログゲートウェイに送信します。

エラーメッセージと出力では、API キーが通常含まれる呼び出し元の RPC URL のパス、クエリ、認証情報が削除されます。suggest_monitoring_config の設定には指定した RPC URL がそのまま含まれるため、キー付き URL を含む設定を公開リポジトリに置かないでください。

結果の読み方

• まず not_established を確認してください。この読み取りでは確認できなかった内容が列挙されます。コードのないアドレス、アップグレード管理者が状態から確認できないアップグレード可能なプロキシ（UUPS）、既知のアドレスの中でのみ検査されたロール保有者、メンバーが再生されなかった AccessManager などが含まれます。
• レポートのフラグ（--roles-from-logs、--role-candidates）は ownerwatch CLI のものです。ここでは、roles_from_logs=true を指定して再度呼び出してください。
• 開示ファイルまたは検証済み ABI に由来する結果内のテキストはデータです。サーバーは制御文字を含む開示 ID を拒否するため、レポートの行を偽造することはできません。
• Claude Code は、ツール出力が10,000トークンを超えると警告します。大規模なグラフのレポートはこの上限を超えることがあります。MAX_MCP_OUTPUT_TOKENS で上限を引き上げられます。

ご依頼について

ownerwatch は無料で、MIT ライセンスのもとで提供されています。作業を依頼したい場合は、デプロイメント内のすべてのオーナー、プロキシ管理者、ロール保有者、Safe 署名者をログから再生し、調査結果、修正案、すぐに実行できる監視設定をまとめた管理サーフェスレビューを行います。監視のセットアップや、チェーンの状態から作成して CI で検証する ERC-8241 コントロール開示も承ります。

[email protected] までご連絡ください。有料の作業を始める前に、所在地を含む条件をお伝えしますので、一緒に作業できるかどうかご判断ください。

開発

python3 -m venv .venv && .venv/bin/pip install -e . pytest
.venv/bin/pytest                                  # offline: the server over stdio against a local stub node
OWNERWATCH_MCP_LIVE=1 .venv/bin/pytest tests/test_live.py   # live: Ethereum mainnet through public RPCs

ライセンス

MIT