git clone <repo-url>
cd lido-mcp-server
npm install

cp .env.example .env

LIDO_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
LIDO_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
LIDO_CHAIN_ID=1

npm run build
npm start

{
  "mcpServers": {
    "lido": {
      "command": "node",
      "args": ["/path/to/lido-mcp-server/dist/index.js"],
      "env": {
        "LIDO_RPC_URL": "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
        "LIDO_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
        "LIDO_CHAIN_ID": "1"
      }
    }
  }
}

User: "Stake 1 ETH with Lido"

Claude: Let me walk you through this safely.
  → Checks protocol status (not paused, limits ok)
  → Checks your balance (1.5 ETH available)
  → Shows current APR (3.4%, 7-day SMA 3.3%)
  → Dry-runs the transaction (gas: 0.002 ETH)
  → "Ready to stake 1 ETH. Gas cost ~0.002 ETH. Confirm?"

User: "Yes"

Claude: → Executes stake
  → "Done. TX: 0xabc... You received 1.0 stETH."

User: "Monitor my Lido position. Alert me if APR drops below 3%
       or my staked amount exceeds 100 ETH."

Claude: → Calls lido_analyze_position with min_apr=3.0, max_position_eth=100
  → "Position: 85.2 ETH staked, APR 3.4%. All within bounds."

[Later, APR drops]

Claude: → Calls lido_analyze_position again
  → "⚠ APR is 2.8% — below your minimum of 3.0%.
     7-day SMA is 3.1%, suggesting this may be temporary.
     Recommend: wait 24h and re-check before withdrawing."

User: "Show me the latest Lido DAO votes"

Claude: → Calls lido_get_aragon_vote
  → "5 most recent votes:
     Vote #185: Open — Yea 15.2M LDO (92%), Nay 1.3M LDO (8%)
     Vote #184: Executed — passed with 98% support
     ..."

User: "Vote yes on #185"

Claude: → Calls lido_vote_on_proposal (dry_run=true)
  → "Dry run: Vote Yea on #185. You have 5,000 LDO. Gas: ~0.001 ETH. Confirm?"

User: "Yes"

Claude: → Calls lido_vote_on_proposal (dry_run=false)
  → "Done. Voted Yea on #185. TX: 0xabc..."

User: "I want to signal opposition to the latest proposal."

Claude: → Calls lido_get_governance_state
  → "Governance is in Normal state. Veto signalling is at 0.12%,
     well below the first seal threshold of 1%."
  → Dry-runs lock of 10 stETH in escrow
  → "Ready to lock 10 stETH for governance. Gas: ~0.003 ETH. Confirm?"

User: "Yes"

Claude: → Approves stETH for escrow + locks
  → "Done. 10 stETH locked in veto signalling escrow. TX: 0xdef..."

User: "Check my wstETH balance on Base"

Claude: → Calls lido_l2_get_wsteth_balance
  → "Balances on Base:
     ETH: 0.5
     wstETH: 10.0
     Note: wstETH on L2 is a bridged token whose value tracks the L1 rate."

src/
├── index.ts              MCP server entry — registers tools, prompts, resources
├── config.ts             Environment validation (RPC, private key, chain)
├── sdk-factory.ts        Viem clients + Lido SDK initialization
├── types.ts              Shared TypeScript types
├── prompts.ts            MCP prompt definitions (guided workflows)
├── resources.ts          MCP resource definitions (live data endpoints)
├── tools/
│   ├── index.ts          Tool router (registration + dispatch)
│   ├── apr.ts            Staking APR queries
│   ├── balances.ts       ETH/stETH/wstETH balance queries
│   ├── convert.ts        Token amount conversion
│   ├── gas.ts            Gas price analysis + break-even calculator
│   ├── governance.ts     Dual governance state + config + warnings
│   ├── aragon-voting.ts  Query & vote on Aragon DAO proposals
│   ├── governance-actions.ts Lock/unlock stETH in veto signalling escrow
│   ├── position.ts       Position analysis with bounds checking
│   ├── protocol-status.ts Stake limits, queue status
│   ├── steth-rate.ts     Share rate + pool composition monitor
│   ├── rewards.ts        Historical staking rewards
│   ├── stake.ts          Stake ETH → stETH
│   ├── withdraw.ts       Request & claim withdrawals
│   ├── withdrawal-status.ts Check withdrawal request status
│   ├── withdrawal-time.ts  Withdrawal finalization time estimator
│   ├── wrap.ts           Wrap/unwrap stETH ↔ wstETH
│   ├── l2-wsteth.ts      L2 wstETH balance, transfer, info (Base/Optimism/Arbitrum)
│   └── l2-steth.ts       L2 rebasing stETH balance + transfer (Optimism only)
└── utils/
    ├── dry-run.ts        Transaction simulation engine
    ├── errors.ts         Protocol-aware error translation
    ├── format.ts         Formatting utilities + Zod schemas
    ├── governance-labels.ts Shared governance state labels
    └── security.ts       Receiver allowlist + amount cap validation