Substreams Search MCP Server

MCP server that lets AI agents search, inspect, and analyze Substreams packages — from registry discovery to sink deployment. Supports dual transport — stdio for local clients and SSE/HTTP for remote agents (OpenClaw, custom frameworks).

Tools

search_substreams

Search the substreams.dev package registry.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string (required) | — | Search term, e.g. "solana dex" or "uniswap" | | sort | string | "most_downloaded" | most_downloaded, alphabetical, most_used, last_uploaded | | network | string | — | Filter by chain: ethereum, solana, arbitrum-one, etc. |

Returns package name, URL, creator, network, version, published date, and download count.

inspect_package

Inspect a Substreams package (.spkg) to see its full module graph, protobuf types, and metadata.

| Parameter | Type | Description | |-----------|------|-------------| | url | string (required) | Direct URL to a .spkg file |

Returns:

• Package metadata (name, version, documentation, network)
• All modules with their kind (map/store/blockIndex), output types, and update policies
• Full DAG: each module's dependsOn and dependedBy relationships
• Input chain for each module (source blocks, other maps, stores with get/deltas mode, params)
• List of all protobuf output types and proto files
• Mermaid diagram of the module graph

list_package_modules

Lightweight alternative to inspect_package — just the module names, types, and inputs/outputs.

| Parameter | Type | Description | |-----------|------|-------------| | url | string (required) | Direct URL to a .spkg file |

get_sink_config

Analyze a package's sink configuration and generate ready-to-run CLI commands.

| Parameter | Type | Description | |-----------|------|-------------| | url | string (required) | Direct URL to a .spkg file |

Returns one of three results:

• sink_configured — Package has an embedded sink config. Extracts the SQL schema (for SQL sinks), identifies the sink module and type, and generates install, setup, and run commands with the correct network endpoint.
• no_sink_config_but_compatible_modules_found — No embedded config, but modules output sink-compatible types (e.g. DatabaseChanges). Identifies them and suggests how to wire up sinking.
• no_sink_support — No sink-compatible modules. Lists all module output types so you know what custom consumer you'd need.

Workflow

search_substreams("uniswap", network: "polygon")
  → find package, get spkg.io URL

inspect_package("https://spkg.io/creator/package-v1.0.0.spkg")
  → see module DAG, output types, what it produces

get_sink_config("https://spkg.io/creator/package-v1.0.0.spkg")
  → get SQL schema + CLI commands to deploy

Quick Start (npx)

No installation needed:

Claude Desktop / Cursor / Claude Code (stdio)

Add to your MCP config (claude_desktop_config.json, ~/.cursor/mcp.json, or ~/.claude/mcp.json):

{
  "mcpServers": {
    "substreams-search": {
      "command": "npx",
      "args": ["substreams-search-mcp"]
    }
  }
}

OpenClaw / Remote Agents (SSE)

Start the server with the HTTP transport:

# Dual transport — stdio + SSE on port 3849
npx substreams-search-mcp --http

# SSE only (for remote/server deployments)
npx substreams-search-mcp --http-only

# Custom port
MCP_HTTP_PORT=4000 npx substreams-search-mcp --http

Then point your agent at the SSE endpoint:

{
  "mcpServers": {
    "substreams-search": {
      "url": "http://localhost:3849/sse"
    }
  }
}

Transport Modes

| Invocation | Transports | Use case | |---|---|---| | npx substreams-search-mcp | stdio | Claude Desktop, Cursor, Claude Code | | npx substreams-search-mcp --http | stdio + SSE :3849 | Dual — local + remote agents | | npx substreams-search-mcp --http-only | SSE :3849 | OpenClaw, remote deployments |

A /health endpoint is available at http://localhost:3849/health when HTTP transport is active.

How it works

• Search: The substreams.dev registry has no public API. This server scrapes the package listing pages, paginates through all results, deduplicates, and returns structured JSON. Multi-word queries search for the first word server-side and filter the rest client-side.
• Inspect: Uses @substreams/core to fetch and parse .spkg files (protobuf-encoded Substreams packages), extracting module definitions, DAG relationships, and proto type information.
• Sink config: Reads the embedded sinkConfig (a google.protobuf.Any field) from the package, decodes it based on the type URL, and maps networks to Substreams endpoints for correct CLI commands.