io.github.PaulieB14/subgraph-registry-mcp
Discover and query 14,700+ classified subgraphs on The Graph Network
Ask AI about io.github.PaulieB14/subgraph-registry-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.PaulieB14/subgraph-registry-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Subgraph Registry
Agent-friendly semantic classification of all subgraphs on The Graph Network.
Pre-computed index of 14,700+ subgraphs with domain classification, protocol type detection, schema fingerprinting, canonical entity mapping, and composite reliability scoring.
The Problem
Agents querying The Graph need to discover and select the right subgraph before they can query data. Today this requires 3-4 tool calls (search, check volumes, fetch schema, infer structure) before any real work happens. This registry flips that: agents start with structured knowledge, not a blank slate.
What It Does
- Crawls all active subgraphs from the Graph Network meta-subgraph
- Fetches the GraphQL schema for every deployment
- Classifies each subgraph by domain, protocol type, canonical entities, and schema family
- Scores reliability using on-chain signals (query fees, volume, curation, stake)
- Publishes as SQLite database + REST API + MCP server
- Generates visual dashboards and bot-readable category files (auto-updated with each sync)
Registry at a Glance
Charts auto-generated from
registry.dbon each sync. Seepython/generate_docs.py.
Browse by Category
Domains
Explore subgraphs by use case β each file lists the top 25 subgraphs ranked by reliability score.
| Domain | Count | File |
|---|---|---|
| DeFi | 11,218 | Swaps, pools, lending, vaults, yield |
| NFTs | 857 | Collections, marketplaces, sales |
| Infrastructure | 581 | Indexers, oracles, registries |
| DAO | 429 | Governance, proposals, voting |
| Identity | 401 | ENS, name services, resolvers |
| Analytics | 327 | Snapshots, metrics, historical data |
| Gaming | 247 | Players, quests, items, worlds |
| Social | 74 | Profiles, posts, follows |
Full index: docs/DOMAINS.md
Networks
Explore subgraphs by blockchain β each file lists the top 25 subgraphs on that chain.
| Network | Count | File |
|---|---|---|
| Ethereum | 2,377 | Largest ecosystem |
| Base | 1,728 | Fast-growing L2 |
| BSC | 1,582 | BNB Chain |
| Arbitrum | 1,376 | Leading L2 |
| Polygon | 1,266 | Polygon PoS |
| Optimism | 568 | OP Stack L2 |
| Avalanche | 440 | C-Chain |
Full index: docs/NETWORKS.md
Protocol Types
| Type | Count | Description |
|---|---|---|
| DEX | 4,176 | Uniswap, Sushi, Curve, Balancer, PancakeSwap |
| Lending | 1,424 | Aave, Compound, Morpho, Spark, Silo |
| Staking | 867 | Lido, Rocket Pool, EigenLayer, Graph Network |
| Bridge | 771 | Hop, Stargate, Across, Wormhole, LayerZero |
| NFT Marketplace | 436 | OpenSea, Blur, Rarible, Foundation |
| Governance | 416 | Snapshot, Tally, Compound Governor |
| Yield Aggregator | 387 | Yearn, Beefy, Harvest, Convex |
| Perpetuals | 266 | GMX, Gains, dYdX, Hyperliquid |
| Name Service | 223 | ENS, Space ID, Unstoppable Domains |
| Options | 179 | Premia, Dopex, Lyra, Hegic |
Reliability Score
Each subgraph gets a composite reliability score (0-1) based on four on-chain signals:
| Signal | Weight | What it measures |
|---|---|---|
| Query Fees | 30% | GRT fees earned from actual usage |
| Query Volume | 30% | 30-day query count |
| Curation Signal | 20% | GRT tokens curated by the community |
| Indexer Allocation | 20% | GRT allocated to this subgraph by indexers |
All values are log-scaled and capped at 1.0. A 0.5 penalty is applied if the subgraph has been denied/deprecated.
Score tiers: High (0.7+) = strong signal, real usage | Medium (0.3-0.7) = functional, some activity | Low (<0.3) = minimal signal or test deployment
MCP Server
The registry is available as an MCP server with dual transport β stdio for local clients and SSE/HTTP for remote agents.
4 tools:
- search_subgraphs β filter by domain, network, protocol type, entity, or keyword
- recommend_subgraph β natural language goal to best subgraphs
- get_subgraph_detail β full classification for a specific subgraph
- list_registry_stats β registry overview (domains, networks, counts)
Install
# Claude Code
claude mcp add subgraph-registry -- npx subgraph-registry-mcp
# Claude Desktop
{
"mcpServers": {
"subgraph-registry": {
"command": "npx",
"args": ["subgraph-registry-mcp"]
}
}
}
# Remote agents (SSE)
npx subgraph-registry-mcp --http-only
# Then connect to http://localhost:3848/sse
The server auto-downloads the pre-built registry (8MB SQLite) from GitHub on first run.
REST API
GET /summary Registry overview and stats
GET /domains Domain breakdown
GET /networks Network breakdown
GET /families Schema family groups (fork/clone detection)
GET /subgraphs Filter subgraphs
GET /subgraphs/{id} Full detail for one subgraph
GET /search?q=uniswap Free-text search
GET /recommend?goal=...&chain= Agent-optimized recommendation
# Start API server
cd python && python server.py
# Example: find DEX subgraphs on Arbitrum
curl "http://localhost:3847/recommend?goal=query+DEX+trades+on+Arbitrum&chain=arbitrum-one"
# Example: filter by entity type
curl "http://localhost:3847/subgraphs?entity=liquidity_pool&network=base&min_reliability=0.5"
Bot-Readable Category Files
The docs/ directory contains structured .md files with YAML frontmatter designed for AI agents and bots to consume:
docs/
βββ DOMAINS.md # Index of all domains with counts
βββ NETWORKS.md # Index of all networks with counts
βββ charts/ # Auto-generated SVG visualizations
β βββ domains.svg
β βββ networks.svg
β βββ protocol-types.svg
β βββ reliability.svg
βββ domains/ # One file per domain
β βββ defi.md # Top 25 DeFi subgraphs by reliability
β βββ nfts.md
β βββ dao.md
β βββ ...
βββ networks/ # One file per network
βββ mainnet.md # Top 25 Ethereum subgraphs by reliability
βββ base.md
βββ arbitrum-one.md
βββ ...
Each category file includes:
- YAML frontmatter (domain/network, count, percentage, last updated)
- Top 25 subgraphs ranked by reliability score
- MCP tool and REST API query examples
Architecture
Graph Network Subgraph (meta-subgraph, 140M queries/month)
|
v
crawler.py ---- async httpx, ID-based cursor pagination
|
v
classifier.py - rule-based domain/protocol classification + schema fingerprinting
|
v
registry.py --- builds SQLite + indices
|
βββ server.py ------ FastAPI REST API (:3847)
βββ generate_docs.py SVG charts + category .md files
βββ scheduler.py --- weekly incremental sync
MCP Server (src/index.js)
βββ stdio βββ Claude Desktop / Claude Code
βββ SSE βββ OpenClaw / remote agents (:3848)
Quick Start (Local Build)
cd python
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
echo "GATEWAY_API_KEY=your-key-here" > .env
# Full crawl + classify (~11 min)
python registry.py
# Generate charts and category files
python generate_docs.py
# Start API server
python server.py
How It Stays Current
A GitHub Actions workflow runs every 3 days:
- Incremental crawl (
updatedAt_gte: lastSyncTimestamp) - Reclassify new/changed subgraphs
- Regenerate SVG charts and category .md files
- Commit and push updates
License
MIT
