# graph-lido-mcp

MCP server for querying Lido liquid staking protocol data via The Graph's decentralized network.

16 tools, 5 guided prompts. Staking stats, APR history, withdrawals, node operators, governance, and more.

## Setup (30 seconds)

1. Get a free API key from [Subgraph Studio](https://thegraph.com/studio/apikeys/)

2. Add to your MCP client config:

```json
{
  "mcpServers": {
    "graph-lido": {
      "command": "npx",
      "args": ["-y", "graph-lido-mcp"],
      "env": {
        "GRAPH_API_KEY": "your-api-key"
      }
    }
  }
}
```

Works with Claude Desktop, Cursor, Cline, and any MCP-compatible client.

## Tools

### Protocol Stats
- **get_lido_stats** - Total pooled ETH, shares, unique holders, fee structure, staking status, withdrawal queue status
- **get_staking_apr** - APR history from oracle reports with fee breakdown and MEV fees

### Staking Activity
- **get_recent_submissions** - Recent stETH deposits with amounts, shares received, referrals
- **get_recent_transfers** - stETH token transfers with optional address and minimum value filters
- **get_holder_shares** - Look up any address's current stETH share balance and computed ETH value

### Withdrawals
- **get_withdrawal_requests** - Pending withdrawal requests (unstaking)
- **get_withdrawal_claims** - Completed withdrawals (ETH received)
- **get_withdrawals_finalized** - Finalization batches (ETH locked, shares burned)
- **get_shares_burns** - Share burn events from withdrawal processing

### Node Operators
- **get_node_operators** - Professional validator operators: names, staking limits, stopped validators

### Oracle
- **get_oracle_reports** - Beacon chain balance and validator count per epoch

### Governance
- **get_governance_votes** - Lido DAO Aragon votes with proposal metadata
- **get_vote_details** - Individual voter records for a specific proposal
- **get_easytrack_motions** - Lightweight governance motions for routine operations

### Escape Hatch
- **get_lido_schema** - Introspect the full GraphQL schema
- **query_lido_subgraph** - Run any raw GraphQL query

## Guided Prompts

| Prompt | Description |
|--------|-------------|
| **staking_overview** | Total ETH staked, current APR trend, recent deposits, holder count |
| **withdrawal_monitor** | Queue health, pending requests, recent claims, net flow direction |
| **governance_digest** | Recent DAO votes, EasyTrack motions, contentious decisions |
| **node_operator_analysis** | Operator set diversity, stopped validators, staking limits |
| **whale_tracker** | Large deposits, big transfers, whale withdrawal patterns |

## Example Prompts

```
"What is the current Lido staking APR?"
"How much total ETH is staked with Lido?"
"Show me whale deposits over 100 ETH"
"Who are Lido's node operators?"
"What's the withdrawal queue status?"
"Show me recent DAO governance votes"
"Look up the stETH balance for 0x..."
"What EasyTrack motions were enacted this month?"
```

## Known Limitations

### shares_collection vs shares

The Lido subgraph uses `_collection` suffix for plural entity queries (e.g., `shares_collection`, `totals_collection`). Standard GraphQL plural naming (`shares`) refers to the singular lookup requiring an `id` argument. If writing raw queries via `query_lido_subgraph`, use the `_collection` suffix to query multiple entities.

### totals(id: "") convention

The Lido subgraph stores singleton entities (like protocol-wide totals) using an empty string as their ID. This is unusual but intentional. Raw queries for totals should use `totals(id: "")`.

## Data Source

All data is queried from Lido's official subgraph deployed on The Graph's decentralized network. Every query generates fees for Indexers on the network. 13 active Indexers serve this subgraph.

- Subgraph: [Graph Explorer](https://thegraph.com/explorer/subgraphs/Sxx812XgeKyzQPaBpR5YZWmGV5fZuBaPdh7DFhzSwiQ)
- Schema: [GitHub](https://github.com/lidofinance/lido-subgraph/blob/master/schema.graphql)
- Docs: [Lido Subgraph Docs](https://docs.lido.fi/integrations/subgraph/)

## License

MIT