Lido MCP Server

Synthesis Hackathon submission — Lido Finance bounty ($5,000 track)

An MCP (Model Context Protocol) server that gives any AI agent full access to Lido Finance's staking infrastructure through natural language. Stake ETH, manage positions, request withdrawals, and monitor protocol stats — all without writing a single line of smart contract code.

---

What Is This?

Think of this like a universal control interface between AI agents and Lido's staking contracts. Like a PLC that speaks plain English instead of ladder logic — the complexity of ABI encoding, gas estimation, and checkpoint hints is abstracted behind simple tool calls.

Any MCP-compatible AI (Claude, GPT-4, etc.) can now say:

• "Stake 0.5 ETH for me"
• "What's my current staking position?"
• "Request a withdrawal of 1 stETH"
• "What's the current APY?"
• "Wrap my stETH into wstETH for use in Aave"

---

Architecture

AI Agent (Claude/GPT)
       │  MCP Protocol (stdio)
       ▼
┌─────────────────────────┐
│   Lido MCP Server       │
│  ┌───────────────────┐  │
│  │  Tool Registry    │  │  ← 10 tools exposed
│  │  (index.ts)       │  │
│  └────────┬──────────┘  │
│           │              │
│  ┌────────▼──────────┐  │
│  │   Lido Client     │  │  ← ethers.js blockchain calls
│  │  (lido-client.ts) │  │
│  └────────┬──────────┘  │
└───────────┼─────────────┘
            │  JSON-RPC
            ▼
    Ethereum Node (RPC)
            │
            ▼
    Lido Smart Contracts
    ├── stETH (0xae7ab96...)
    ├── wstETH (0x7f39C5...)
    └── WithdrawalQueue (0x889ed...)

---

Available Tools

Tool	Description	Requires Wallet
get_staking_position	Full position: ETH, stETH, wstETH balances	No
stake_eth	Deposit ETH → receive stETH	Yes
request_withdrawal	stETH → withdrawal NFT	Yes
get_withdrawal_requests	List all pending/finalized requests	No
claim_withdrawal	Claim finalized withdrawal → ETH	Yes
wrap_to_wsteth	stETH → wstETH (for DeFi protocols)	Yes
get_lido_apy	Current staking APY (SMA + last epoch)	No
get_protocol_stats	Total staked, stakers, market cap	No
convert_steth_to_eth	stETH amount → ETH value at live rate	No
get_network_info	Connected network and contract addresses	No

---

Setup

Prerequisites

• Node.js 18+
• An Ethereum RPC URL (free tier: Alchemy, Infura, or public RPCs)

Install

git clone <this-repo>
cd lido-mcp-server
npm install
npm run build

Environment Variables

# Required
ETH_RPC_URL=https://eth-holesky.g.alchemy.com/v2/YOUR_KEY

# Network (mainnet | holesky | goerli) — default: holesky
LIDO_NETWORK=holesky

# Optional — enables staking/withdrawal transactions
PRIVATE_KEY=0xYOUR_PRIVATE_KEY

# Optional — referral address for Lido (get a cut of fees)
LIDO_REFERRAL=0xYOUR_REFERRAL_ADDRESS

⚠️ Security: Never expose your private key. Use a dedicated wallet for the agent with only the ETH you're comfortable having it manage. This is like giving someone a company card with a spending limit — not your main account.

Run

# Production
npm start

# Development
npm run dev

Connect to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "lido": {
      "command": "node",
      "args": ["/path/to/lido-mcp-server/dist/index.js"],
      "env": {
        "ETH_RPC_URL": "https://eth-holesky.g.alchemy.com/v2/YOUR_KEY",
        "LIDO_NETWORK": "holesky",
        "PRIVATE_KEY": "0x..."
      }
    }
  }
}

Connect to Claude Code / Any MCP Client

ETH_RPC_URL=<rpc> LIDO_NETWORK=holesky PRIVATE_KEY=0x... node dist/index.js

---

Example Conversations

Checking a position

User: How much have I staked on Lido?
Claude: [calls get_staking_position with your address]
→ "You have 2.4731 stETH (worth ~2.4819 ETH) and 0 wstETH on holesky."

Staking ETH

User: Stake 0.1 ETH for me
Claude: [calls stake_eth with eth_amount: "0.1"]
→ "Successfully staked 0.1 ETH and received 0.0997 stETH.
   Transaction: https://holesky.etherscan.io/tx/0x..."

Monitoring APY

User: What's the current Lido yield?
Claude: [calls get_lido_apy]
→ "Current Lido staking APY: 3.82% (7-day SMA). Most recent epoch: 3.91%"

---

Security Model

• Read-only by default: Without PRIVATE_KEY, all write operations return a clear error message. No accidental transactions.
• No key exposure: The private key is only used to sign transactions — it's never logged or returned in tool responses.
• Testnet first: Default network is Holesky testnet. Explicitly set LIDO_NETWORK=mainnet to use real funds.
• Balance checks: All stake/withdraw tools verify sufficient balance before broadcasting.
• Withdrawal limits: Enforced at contract level + validated before submission to prevent failed transactions.

---

On-Chain Addresses

Mainnet

• stETH: 0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84
• wstETH: 0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0
• WithdrawalQueue: 0x889edC2eDab5f40e902b864aD4d7AdE8E412F9B4

Holesky (testnet)

• stETH: 0x3F1c547b21f65e10480dE3ad8E19fAAE172E1fBf
• wstETH: 0x8d09a4502Cc8Cf1547aD300E066060D043f6982D
• WithdrawalQueue: 0xc7cc160b58F8Bb0baC94b80847E2CF2800565C50

---

Bounty Context (Lido Finance — $5,000)

This submission targets the reference MCP server sub-bounty:

"A reference MCP server so any AI can stake funds and manage positions through a natural language conversation ($5,000)"

What makes this more than a basic integration:

1. Full lifecycle coverage: stake → hold → wrap for DeFi → unwrap → withdraw → claim
2. Testnet-first design: Safe defaults, real credentials optional
3. Production error handling: Balance checks, finalization guards, chunk splitting for large withdrawals
4. Zero-setup read mode: APY, stats, and position queries work without any wallet
5. Composable: Designed so other agents can use this as a building block

---

License

MIT