Substreams Search MCP Server

MCP server that lets AI agents search, inspect, and analyze Substreams packages — from registry discovery to sink deployment.

Tools

search_substreams

Search the substreams.dev package registry.

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.

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.

get_sink_config

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

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

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Cursor

Add to ~/.cursor/mcp.json:

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

Claude Code

Add to ~/.claude/mcp.json:

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

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.