Nothing to install and nothing to set up: the server serves a local page, and that page talks to whatever wallet extension your browser already has. The first transaction opens it, you connect MetaMask, Rabby or Coinbase once, and every later request lands in that same tab.

One relay per machine — all your editor sessions share the page, so you connect once and a transaction from any session shows up there. The page and the server are both clients of a local relay on 127.0.0.1:3456 (next free port up to 3460), authenticated with a pairing token carried in the URL fragment (#t=…) of the link the server prints. The token lives in ~/.config/web3-tools-mcp/relay-token (mode 0600) — delete it to rotate.

Works with MetaMask, Rabby, Coinbase Wallet, and any EIP-1193 browser wallet. wallet_status returns the page URL any time you want to open it yourself.

✍️ Transactions & signing

The four signing tools take a required signWith of phone or browser. There is no default on purpose — the agent has to ask you, so a request never lands on a device you are not holding. On localhost only the browser can sign; a phone has no route to your node. With several phones paired, the optional account picks one by address; omitted, the most recently paired is used.

A request not approved within the call comes back with a requestId instead of hanging, and check_signing_request collects it — asking again would put a second prompt in front of your wallet.

📜 Contracts

⛓️ Chain data

Tracing prefers an RPC that exposes debug_*, and otherwise uses a node you already run at ANVIL_RPC_URL (default 127.0.0.1:8545, e.g. anvil --fork-url …) — nothing is started for you. Replaying a transaction older than the fork re-forks that node, clearing its state, so it happens only with ANVIL_ALLOW_RESET=1. A hosted server has no default and traces only through an explicit ANVIL_RPC_URL.

🏷️ ENS

ENS tools take mainnet (ENS), linea (Linea Names) or base (Basenames).

Adding one is a single entry in mcp/src/chains.ts.

Add the entry below to your client's MCP config, then restart the app. Every one of these also has a UI route that creates the file for you, which is usually quicker than finding it:

{
  "mcpServers": {
    "web3-tools": {
      "command": "npx",
      "args": ["-y", "web3-tools-mcp"],
      "env": {
        "WALLETCONNECT_PROJECT_ID": "<your project id>",
        "ETHERSCAN_API_KEY": "<your key>"
      }
    }
  }
}

Drop the whole env block if you have no keys yet: the server runs without them, with less reach. 🔑 API keys below says exactly what each one turns on.

⚠️ VS Code is the exception. Its mcp.json nests servers under "servers", not "mcpServers" — paste the block above unchanged and it is silently ignored:

{ "servers": { "web3-tools": { "command": "npx", "args": ["-y", "web3-tools-mcp"] } } }

claude mcp add --scope user --transport stdio web3-tools -- npx -y web3-tools-mcp

Or, against a hosted instance:

claude mcp add --transport http web3-tools https://your-host/mcp \
  --header "Authorization: Bearer <MCP_TOKEN>"

None of these can launch a local process, so they need a hosted instance: deploy one ↓, then point the client at https://your-host/mcp.

ChatGPT — Settings → Apps & Connectors → Advanced → enable Developer mode, then Create. Give it a name and the server URL. The URL has to include the /mcp path; that is the usual mistake. Pick OAuth and it walks you through the login page the server serves, or pick token and paste MCP_TOKEN. Needs a paid plan.

Grok — grok.com/connectors → New Connector → Custom, then the same URL and authentication. Needs a paid plan.

claude.ai — Settings → Connectors → Add custom connector, then the URL. It uses OAuth, which the server implements against MCP_TOKEN: it shows a page asking for the token and issues one once you paste it.

Once connected, pair your phone and approvals arrive there — no laptop in the loop at all.

Nothing here is required to start, and the server will not refuse to run without any of it. What you lose is reach, not stability — so here is the honest version:

So with nothing configured you get current balances, contract reads, gas, ENS, simulation and browser signing. Add WALLETCONNECT_PROJECT_ID for your phone and one provider key for history, and everything above lights up.

Every key has a matching flag (--etherscan-api-key, …), RPC selection falls back Alchemy → public, and CUSTOM_RPC overrides both, chain by chain. npx web3-tools-mcp --help lists them; .env.example documents each one.

npx web3-tools-mcp --etherscan-api-key KEY --walletconnect-project-id ID

There is a plain Dockerfile too, so Railway, Cloud Run or your own box work the same way:

docker build -t web3-tools-mcp .
docker run -p 8080:8080 \
  -e MCP_TOKEN=<long random string> \
  -e MCP_PUBLIC_URL=https://your-host \
  -e WALLETCONNECT_PROJECT_ID=<id> \
  web3-tools-mcp

Then point a client at it:

claude mcp add --transport http web3-tools https://your-host/mcp \
  --header "Authorization: Bearer <MCP_TOKEN>"

Clients that cannot send a header — claude.ai connectors, and the browser and phone apps — use OAuth, which the server implements against the same credential: it shows a page asking for MCP_TOKEN and issues a token once you paste it. No identity provider, no accounts.

🔐 MCP_TOKEN is mandatory and the server refuses to start without it. Anyone who reaches /mcp while your phone is paired can push signing prompts at it. You would still approve each one, but that is a phishing surface, not a feature.

Two things decide whether the pairing survives:

• ⏰ Keep the instance awake. Sleeping drops the WalletConnect socket, so the first transaction after an idle period waits for the host to wake — about a minute on a free tier.
• 💾 Give the session somewhere durable. Most hosts have an ephemeral filesystem, so a plain file is lost on redeploy and you rescan the QR. Attach a volume and point XDG_CONFIG_HOME at it (what render.yaml and fly.toml do), or set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN (Upstash has a free plan).

Render's free Key Value instance is not an option here — no persistence, so the pairing disappears at its next maintenance.

Both signers work on a hosted instance. The signing page is served from the same port as /mcp, so https://your-host/sign/#t=<relay token> is your wallet page — no second service to deploy. The root is left free for a page of your own. Ask the agent for wallet_status to get the link; it is behind MCP_TOKEN and never written to the logs. Unless you set WALLET_TOKEN, the relay secret is minted fresh each boot rather than stored, so the URL changes when you redeploy.

The relay is its own package, web3-wallet-relay, and runs anywhere that keeps a Node process alive and supports WebSockets. Its README covers hosting it; run it at this server's version, then point the server at it with WALLET_SERVER_URL and the same WALLET_TOKEN.

Locally nothing changes: the server embeds the same relay.