Lido MCP Server

The reference MCP server for Lido — stETH staking, position management, governance, and earn vault monitoring, all natively callable by any AI agent.

Point Claude, Cursor, or any MCP-compatible agent at this server and stake ETH from a conversation. No custom integration code needed.

Why This Exists

AI agents need to interact with DeFi protocols, but bridging natural language to on-chain transactions is hard — private keys, gas estimation, protocol quirks (stETH rebasing), transaction safety. This MCP server gives agents a structured, safe interface to Lido:

• Every write operation supports dry-run simulation — agents preview gas costs and verify transactions before executing

• A mental model document (lido.skill.md) teaches agents Lido concepts before they act — rebasing mechanics, wstETH vs stETH tradeoffs, safe staking patterns

• Live vault monitoring with intelligent alerts — watch Lido Earn vaults for yield changes, TVL shifts, share price anomalies, and protocol allocation shifts (Aave, Morpho, Pendle, Gearbox, Maple), with alerts in plain language via Telegram or email

• Flexible rule engine — define alert conditions as readable expressions like apr < 3.0 or spread_vs_steth < -0.5, with automatic stETH benchmark comparison

• AI-powered explanations — optionally uses Claude to translate raw vault events into plain-language messages explaining what changed, why, and whether you need to act

• Security guardrails — read-only, dry-run-only, and full modes, receiver allowlists, per-transaction ETH caps

MCP Server

70+ tools across staking, governance, vault monitoring, and L2 — every write operation defaults to dry_run: true.

6 guided prompts — multi-step workflows for staking (stake-eth-safely), position analysis (manage-position), withdrawals (withdraw-steth), governance review (review-governance), vault management (manage-vault), and governance participation (participate-governance).

4 live resources — lido://position/{address}, lido://protocol/status, lido://governance/state, lido://governance/votes.

Agent mental model (lido.skill.md) — see "Why This Exists" above.

Key Design Decisions

• Real SDK, no mocks — all operations go through @lidofinance/lido-ethereum-sdk and viem to actual Ethereum contracts

• Dry-run by default — every state-changing tool defaults to dry_run: true. Agents must explicitly set dry_run: false to execute

• Protocol-aware errors — raw blockchain errors (insufficient funds, reverts, nonce conflicts, stake limits, paused) are translated to human-readable messages

• MCP annotations — every tool declares readOnlyHint, destructiveHint, idempotentHint, and openWorldHint so agents know which tools are safe to call without confirmation

• L2 aware — set LIDO_CHAIN_ID to Base, Optimism, or Arbitrum and the server exposes only wstETH-specific tools; L1-only tools are excluded automatically

Earn Vault Monitor

Watches Lido Earn vaults (EarnETH, EarnUSD) and tells depositors when something worth knowing has changed — in plain language, not raw data.

How It Works

1. Watch a vault — call lido_watch_vault with a vault address (use lido_list_earn_vaults to discover them)

2. Define alert rules — write conditions as readable expressions evaluated against live vault data

3. Receive alerts — get notified via Telegram or email when rules fire, with AI-generated explanations

The monitor runs continuously:

• Subscribes to on-chain Deposit/Withdraw events on each vault and TokenRebased on stETH for near-real-time reaction

• Runs a 30-second polling health check as a fallback

• Compares vault APR against the stETH SMA APR from the Lido API on every check

• Detects protocol allocation shifts across underlying protocols (Aave, Morpho, Pendle, Gearbox, Maple) by reading on-chain subvault balances for known Lido Earn vaults

• Persists all state (watches, snapshots, alerts, dedup) in SQLite — survives restarts

• 6-hour dedup window per rule per vault prevents alert fatigue

Alert Delivery

• Telegram — formatted alerts with severity indicators, vault context, benchmark comparison, and actionable guidance

• Email — HTML-formatted alerts with the same context

• AI explanations (optional) — when ANTHROPIC_API_KEY is set, each alert is passed to Claude which generates a plain-language explanation covering:

  1. What changed — the specific metric that triggered the alert

  2. Why it likely happened — plausible explanations based on the data

  3. What to consider — whether the depositor should act, wait, or investigate

Rule Engine

Rules aren't a fixed set of predefined alerts — they're open-ended expressions you define in natural language through the agent. Tell Claude "alert me if yield drops below 3%" and it writes the rule apr < 3.0. Say "notify me if the vault starts underperforming stETH by more than half a percent while TVL is also dropping" and it composes spread_vs_steth < -0.5 and tvl_change_pct < 0. The agent translates your intent into a mathjs expression evaluated against live vault metrics:

Example rules:

Supports and/or/not boolean logic, comparison operators (<, >, <=, >=, ==, !=), arithmetic (+, -, *, /), and safe math functions (abs, min, max, round, floor, ceil, sqrt).

Each rule includes a message template with {{variable}} interpolation:

APR dropped to {{apr}}%, below your 3% floor. stETH is at {{steth_apr}}%.

If no message is provided, one is auto-generated from the expression pattern.

The rule engine is sandboxed — expressions are parsed into an AST and validated against an allowlist of variables, functions, and node types. No arbitrary code execution.

Protocol Allocation Detection

For known Lido Earn vaults (strETH/EarnETH), the monitor reads on-chain balances across each vault subvault to determine how capital is distributed across underlying protocols — Aave, Morpho, Pendle, Gearbox, Maple, and others. Each health check compares the current allocation to the previous snapshot and detects shifts.

Allocation data appears in:

• Health reports (lido_check_vault) — shows per-protocol percentage breakdown

• Alert context — when any rule fires, the alert includes allocation shift details (protocol name, from/to percentages, delta)

• AI explanations — the LLM receives allocation shift data and can explain rebalancing events in plain language

• Rule variables — max_alloc_shift, num_protocols, and top_alloc_pct let you write rules like max_alloc_shift > 10 (alert when any protocol's share shifts by more than 10pp)

MCP-Callable Vault Health

Other agents can query vault health programmatically — the monitor isn't just a notification service, it's a building block:

• lido_check_vault — on-demand health check for any ERC-4626 vault (no watch required). Returns APR, TVL, share price, and stETH benchmark spread

• lido_list_earn_vaults — discover available Mellow earn vaults from the live API

• lido_get_vault_alerts — query alert history programmatically

Target Use Cases

1. Developer stakes ETH via Claude — zero integration code

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."

2. Depositor gets a Telegram message explaining why EarnETH yield dropped overnight

User: "Watch the EarnETH vault. Alert me if yield drops below 4%
       or it falls behind raw stETH staking."

Claude: → Discovers vault via lido_list_earn_vaults
  → Calls lido_watch_vault with rules:
    - apr < 4.0 [warning]
    - spread_vs_steth < 0 [critical]
  → "Watching EarnETH (0x...). APR: 5.2%, TVL: 12,450 ETH.
     You'll get a Telegram alert if APR drops below 4%
     or the vault underperforms stETH."

[Overnight, APR drops to 3.6%]

Telegram: 🚨 EarnETH — Warning

  APR dropped to *3.60%*, down from 5.20%.

  The vault's yield fell 1.6pp since the last check. This likely
  reflects a rotation in the underlying strategy or temporary
  market conditions. The vault is still outperforming direct stETH
  staking (3.40%) by 0.20pp, so no immediate action is needed —
  but worth monitoring if the trend continues.

  • Current APR: 3.60%
  • Previous APR: 5.20%
  • stETH benchmark: 3.40%
  • Spread vs stETH: 0.20pp above

  View on Etherscan

3. Agent queries vault health before deciding to deposit

Agent: → Calls lido_check_vault(address="0x...")

Response:
  === Vault Health: EarnETH ===
  TVL: 12,450.00 ETH
  Share Price: 1.034521 ETH/share
  APR: 5.20%

  --- Benchmark ---
  stETH APR (SMA): 3.40%
  Spread: 1.80pp above stETH benchmark

  --- Protocol Allocations ---
  Aave: 32.1%
  Morpho: 28.4%
  Pendle: 18.7%
  Gearbox: 12.3%
  Maple: 8.5%

  Last checked: 2025-03-23T14:30:00.000Z

Agent: → Diversified allocation, positive spread — decides to deposit

4. Natural-language rule configuration

User: "I want to know if the vault starts doing worse than just
       holding stETH, especially if people are also pulling money out.
       And give me a heads up if the share price ever drops suddenly —
       that could mean something bad happened."

Claude: I'll set up three rules for you.
  → Calls lido_add_rule: "spread_vs_steth < 0 and tvl_change_pct < -5" [warning]
    Message: "Vault underperforming stETH (spread {{spread_vs_steth}}pp)
              while TVL dropped {{tvl_change_pct}}%"
  → Calls lido_add_rule: "share_price_change_pct < -0.1" [critical]
    Message: "Share price dropped {{share_price_change_pct}}% — investigate immediately"
  → Calls lido_add_rule: "spread_vs_steth < -1.0" [critical]
    Message: "Vault is {{spread_vs_steth}}pp behind stETH — significant underperformance"

  "Done. Three rules active:
   1. Warning if the vault trails stETH while TVL is declining
   2. Critical alert on any sudden share price drop (>0.1%)
   3. Critical if the vault falls more than 1pp behind stETH

   Dry-ran all three against current data — none would fire right now
   (APR 5.2% vs stETH 3.4%, TVL stable). You'll get alerts the
   moment any condition is met."

5. DAO contributor queries and votes on governance proposals

User: "Show me the latest Lido DAO votes"

Claude: → Calls lido_get_aragon_vote
  → "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: → Executes vote
  → "Done. Voted Yea on #185. TX: 0xabc..."

6. Staker signals opposition via Dual Governance

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..."

Setup

git clone <repo-url>
cd lido-mcp-server
cp .env.example .env  # edit with your RPC URL, private key, chain ID
npm install && npm run build && npm start

See .env.example for all configuration options (chain ID, security mode, Telegram, SMTP, Anthropic).

Connect to Claude / Cursor

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

License

MIT