wc-mcp

A local stdio MCP server that connects to your EVM wallet via WalletConnect QR code, exposes read and sign tools, and persists the session across restarts.

Non-custodial. The server never holds private keys — all signing happens in your mobile wallet over the WalletConnect relay.

Prerequisites

• Node.js 20+
• pnpm 10+
• A WalletConnect Project ID (free, see below)
• A mobile wallet that supports WalletConnect v2 (Trust Wallet, MetaMask Mobile, Rainbow, etc.)

Getting a WalletConnect Project ID

1. Go to cloud.reown.com (formerly WalletConnect Cloud).
2. Sign up / log in.
3. Create a new project → copy the Project ID.
4. Set it as an environment variable:

export WALLETCONNECT_PROJECT_ID=your_project_id_here

Installation

pnpm install
pnpm build

MCP host configuration

Add this to your MCP host config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "wc-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/wc-mcp/dist/index.js"],
      "env": {
        "WALLETCONNECT_PROJECT_ID": "your_project_id_here"
      }
    }
  }
}

Or if installed globally via npm link / npx:

{
  "mcpServers": {
    "wc-mcp": {
      "command": "wc-mcp",
      "env": {
        "WALLETCONNECT_PROJECT_ID": "your_project_id_here"
      }
    }
  }
}

Available tools

| Tool | Description | |------|-------------| | connect | Initiate a WC session — returns a unicode QR + raw wc: URI | | disconnect | Disconnect the active session | | status | Show connection status, address, and chain id | | get_balance | Read ETH balance via viem (no wallet needed) | | get_chain_id | Read chain id from the configured RPC (no wallet needed) | | send_transaction | Send an EVM transaction (wallet approval required) | | personal_sign | Sign a message with personal_sign (wallet approval required) |

Manual steps for the full connect → sign → persist loop

These steps require a real project ID and a mobile wallet — they cannot be automated in a test:

1. Connect

Ask the MCP host to call the connect tool. The server returns:

• A unicode QR code (display in terminal or MCP host UI)
• A raw wc: URI you can paste into your wallet's WC scanner
• A deep link for direct mobile wallet open

Scan the QR or paste the URI in your mobile wallet and approve the connection request.

2. Verify connection

Call the status tool — it should return connected with your CAIP-10 address and chain id.

3. Read

Call get_balance with your address and chain_id: 11155111 (Sepolia) — verify it matches the block explorer.

4. Sign / send

Call personal_sign with a test message, or send_transaction with a minimal Sepolia transfer (e.g. value: "0x0" to your own address). Your mobile wallet will show an approval prompt.

5. Restart persistence test

Stop and restart the MCP server. Call status — it should return connected without needing to scan the QR again. This confirms both persistence layers are working:

• Layer a (WC SignClient session): stored in ~/.wc-mcp/ via the storage option forwarded into SignClient.init
• Layer b (lastConnectedWalletId): stored in ~/.wc-mcp/ via the StorageBackend injected into TrustConnect({ storage })

Optional environment variables

| Variable | Default | Description | |----------|---------|-------------| | WALLETCONNECT_PROJECT_ID | required | Reown dashboard project ID | | RPC_URL_MAINNET | https://cloudflare-eth.com | Override mainnet RPC | | RPC_URL_SEPOLIA | https://rpc.sepolia.org | Override Sepolia RPC |

Session storage

All session data is stored in ~/.wc-mcp/ (JSON files). Delete this directory to clear all sessions and start fresh.

Development

pnpm check:type   # TypeScript typecheck
pnpm build        # Build dist/index.js
pnpm test         # Acceptance #0 headless boot test
pnpm check:fix    # Biome lint + format