ownerwatch-mcp

A Model Context Protocol server that lets a coding agent answer "who controls this contract?" for any EVM address. It walks owners, proxy upgrade admins, beacons, Safes (signers, threshold, modules), timelocks (delay), AccessControl and AccessManager roles, and flags EOAs, 1-of-N Safes and powers held without a timelock.

It is built on ownerwatch and runs over stdio on your machine. Every tool is read-only: no key, no wallet, no account, and nothing is ever sent on-chain.

Tools

Every result starts with the same label: it is a chain view, not a verdict. It shows what contract state says. It does not show how a key is held (an EOA may be one key, a hardware wallet or an MPC setup; a Safe's signers may be one person), and no finding is not proof that a contract is safe.

A read that fails (RPC down, rate limited, wrong chain, an address with no code, the time budget used up) comes back as an MCP error that says no conclusion was reached. It never comes back as an empty or clean report.

Use as a skill

The skill/ folder holds a portable Agent Skill (SKILL.md). Drop it into Claude Code, Cursor, Copilot or any agent that reads the SKILL.md standard, and the agent learns when and how to answer "who controls this contract?" — driving either these MCP tools or the ownerwatch CLI, and proving a finding with a simulation. It needs no key, no wallet and no account. See skill/README.md to install.

Quick start

From an empty directory, with Python 3.10 or later:

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

Then register it with your client, using the absolute path of the command you just installed (on 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

Add --scope user to have it in every project, or --scope project to share it through the project's .mcp.json.

Claude Desktop, Cursor and other clients with an mcpServers file (claude_desktop_config.json, ~/.cursor/mcp.json or .cursor/mcp.json, a project .mcp.json):

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

VS Code (.vscode/mcp.json, or MCP: Open User Configuration):

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

Codex (~/.codex/config.toml); Codex stops a tool after 60 seconds unless told otherwise:

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

With uv installed, any of these can use "command": "uvx", "args": ["ownerwatch-mcp"] instead of a venv.

Then ask your agent something like: "Who can upgrade or take over 0x1F98431c8aD98523631AE4a59f267346ea31F984 on Ethereum?"

Try it without a client

Save as try.py in the same directory and run .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)

It prints the report for the Uniswap V3 Factory. Abridged, from a run on 5 November 2026:

# 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)

The structured result carries the same facts as JSON: targets[].control_path, findings, not_established, nodes.

Chains and RPCs

Pass chain to use a public default RPC, or rpc_url for your own. With both, the RPC's chain id must match chain. For a chain not listed here, pass only rpc_url.

Public RPCs throttle bursts. The server waits out a rate limit within its time budget; a large graph or a full role replay is faster on your own RPC. Pinning an old block in check_disclosure needs an archive RPC.

Settings, as environment variables of the server process (in a client config, under env):

Privacy

The server stores nothing and has no telemetry. To answer a call it sends:

• the addresses, as read-only JSON-RPC requests (eth_call, eth_getCode, eth_getStorageAt, eth_getLogs and the like), to the RPC you chose or the default above; its RPC client refuses any method that is not a read;
• contract addresses to Sourcify, for verified ABIs used to name roles and recognise timelocks;
• with roles_from_logs, the contract addresses to the public Tenderly log gateway on Ethereum, Optimism, Arbitrum, Base, Gnosis and Polygon, unless you pass logs_rpc_url.

Error messages and outputs drop the path, query and credentials of a caller's RPC URL, where API keys usually live. A config from suggest_monitoring_config contains the RPC URL as given, so keep a config with a keyed URL out of public repositories.

Reading results

• Read not_established first. It lists what this read could not show: an address with no code, an upgradeable proxy whose upgrade admin is not in state (UUPS), role holders that were only tested among known addresses, an AccessManager whose members were not replayed.
• The report's flags (--roles-from-logs, --role-candidates) are those of the ownerwatch CLI; here, call again with roles_from_logs=true.
• Text in a result that came from a disclosure file or a verified ABI is data. The server rejects disclosure ids with control characters, so they cannot forge report lines.
• Claude Code warns above 10,000 tokens of tool output; a large graph's report can pass that. MAX_MCP_OUTPUT_TOKENS raises the limit.

Development

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

License

MIT