|
| 1 | +--- |
| 2 | +title: Substreams Search MCP |
| 3 | +sidebarTitle: Substreams Search |
| 4 | +--- |
| 5 | + |
| 6 | +MCP server that lets AI agents search, inspect, and analyze [Substreams](https://substreams.dev) packages — from registry discovery to sink deployment. Supports dual transport for local clients and SSE/HTTP for remote agents (OpenClaw, custom frameworks). |
| 7 | + |
| 8 | +## Tools |
| 9 | + |
| 10 | +### Search Substreams |
| 11 | + |
| 12 | +`search_substreams`: Search the substreams.dev package registry. |
| 13 | + |
| 14 | +| Parameter | Type | Default | Description | |
| 15 | +| --- | --- | --- | --- | |
| 16 | +| `query` | string (required) | — | Search term, e.g. `"solana dex"` or `"uniswap"` | |
| 17 | +| `sort` | string | `"most_downloaded"` | `most_downloaded`, `alphabetical`, `most_used`, `last_uploaded` | |
| 18 | +| `network` | string | — | Filter by chain: `ethereum`, `solana`, `arbitrum-one`, etc. | |
| 19 | + |
| 20 | +Returns package name, URL, creator, network, version, published date, and download count. |
| 21 | + |
| 22 | +### Inspect Package |
| 23 | + |
| 24 | +`inspect_package`: Inspect a Substreams package (.spkg) to see its full module graph, protobuf types, and metadata. |
| 25 | + |
| 26 | +| Parameter | Type | Description | |
| 27 | +| --------- | ----------------- | ---------------------------- | |
| 28 | +| `url` | string (required) | Direct URL to a `.spkg` file | |
| 29 | + |
| 30 | +Returns: |
| 31 | + |
| 32 | +- Package metadata (name, version, documentation, network) |
| 33 | +- All modules with their kind (map/store/blockIndex), output types, and update policies |
| 34 | +- Full DAG: each module's `dependsOn` and `dependedBy` relationships |
| 35 | +- Input chain for each module (source blocks, other maps, stores with get/deltas mode, params) |
| 36 | +- List of all protobuf output types and proto files |
| 37 | +- Mermaid diagram of the module graph |
| 38 | + |
| 39 | +### List Package Modules |
| 40 | + |
| 41 | +`list_package_modules`: Lightweight alternative to `inspect_package` — just the module names, types, and inputs/outputs. |
| 42 | + |
| 43 | +| Parameter | Type | Description | |
| 44 | +| --------- | ----------------- | ---------------------------- | |
| 45 | +| `url` | string (required) | Direct URL to a `.spkg` file | |
| 46 | + |
| 47 | +### Get Sink Configuration |
| 48 | + |
| 49 | +`get_sink_config`: Analyze a package's sink configuration and generate ready-to-run CLI commands. |
| 50 | + |
| 51 | +| Parameter | Type | Description | |
| 52 | +| --------- | ----------------- | ---------------------------- | |
| 53 | +| `url` | string (required) | Direct URL to a `.spkg` file | |
| 54 | + |
| 55 | +Returns one of three results: |
| 56 | + |
| 57 | +- **`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. |
| 58 | +- **`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. |
| 59 | +- **`no_sink_support`** — No sink-compatible modules. Lists all module output types so you know what custom consumer you'd need. |
| 60 | + |
| 61 | +## Workflow |
| 62 | + |
| 63 | +``` |
| 64 | +search_substreams("uniswap", network: "polygon") |
| 65 | + → find package, get spkg.io URL |
| 66 | +
|
| 67 | +inspect_package("https://spkg.io/creator/package-v1.0.0.spkg") |
| 68 | + → see module DAG, output types, what it produces |
| 69 | +
|
| 70 | +get_sink_config("https://spkg.io/creator/package-v1.0.0.spkg") |
| 71 | + → get SQL schema + CLI commands to deploy |
| 72 | +``` |
| 73 | + |
| 74 | +## Quick Start (npx) |
| 75 | + |
| 76 | +No installation needed: |
| 77 | + |
| 78 | +### Claude Desktop / Cursor / Claude Code |
| 79 | + |
| 80 | +Add to your MCP config (`claude_desktop_config.json`, `~/.cursor/mcp.json`, or `~/.claude/mcp.json`): |
| 81 | + |
| 82 | +```json |
| 83 | +{ |
| 84 | + "mcpServers": { |
| 85 | + "substreams-search": { |
| 86 | + "command": "npx", |
| 87 | + "args": ["substreams-search-mcp"] |
| 88 | + } |
| 89 | + } |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +### OpenClaw / Remote Agents (SSE) |
| 94 | + |
| 95 | +Start the server with the HTTP transport: |
| 96 | + |
| 97 | +```bash |
| 98 | +# Dual transport — stdio + SSE on port 3849 |
| 99 | +npx substreams-search-mcp --http |
| 100 | + |
| 101 | +# SSE only (for remote/server deployments) |
| 102 | +npx substreams-search-mcp --http-only |
| 103 | + |
| 104 | +# Custom port |
| 105 | +MCP_HTTP_PORT=4000 npx substreams-search-mcp --http |
| 106 | +``` |
| 107 | + |
| 108 | +Then point your agent at the SSE endpoint: |
| 109 | + |
| 110 | +```json |
| 111 | +{ |
| 112 | + "mcpServers": { |
| 113 | + "substreams-search": { |
| 114 | + "url": "http://localhost:3849/sse" |
| 115 | + } |
| 116 | + } |
| 117 | +} |
| 118 | +``` |
| 119 | + |
| 120 | +### Transport Modes |
| 121 | + |
| 122 | +| Invocation | Transports | Use case | |
| 123 | +| --------------------------------------- | ----------------- | ----------------------------------- | |
| 124 | +| `npx substreams-search-mcp` | stdio | Claude Desktop, Cursor, Claude Code | |
| 125 | +| `npx substreams-search-mcp --http` | stdio + SSE :3849 | Dual — local + remote agents | |
| 126 | +| `npx substreams-search-mcp --http-only` | SSE :3849 | OpenClaw, remote deployments | |
| 127 | + |
| 128 | +A `/health` endpoint is available at `http://localhost:3849/health` when HTTP transport is active. |
| 129 | + |
| 130 | +## How it works |
| 131 | + |
| 132 | +- **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. |
| 133 | +- **Inspect**: Uses [`@substreams/core`](https://github.com/substreams-js/substreams-js) to fetch and parse `.spkg` files (protobuf-encoded Substreams packages), extracting module definitions, DAG relationships, and proto type information. |
| 134 | +- **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. |
| 135 | + |
| 136 | +## Acknowledgments |
| 137 | + |
| 138 | +Thanks for PaulieB for creating the [Substreams Search MCP](https://github.com/PaulieB14/substreams-search-mcp) |
0 commit comments