DeFiStream MCP Server

Model Context Protocol (MCP) server that wraps the DeFiStream REST API, giving LLMs (Claude Desktop, Claude Code, etc.) direct access to on-chain DeFi event data. Make sure to get an api key from app.defistream.deveasily.

Quick Start

# Install
cd mcp-server
pip install -e .

# Set your API key
export DEFISTREAM_API_KEY="dsk_your_key_here"

# Run (stdio transport)
defistream-mcp

Docker

No Python installation required — run the MCP server directly from Docker Hub:

docker run -i -e DEFISTREAM_API_KEY=dsk_your_key_here defistream/mcp-server

Claude Code

claude mcp add --transport stdio defistream \
  -- docker run -i -e DEFISTREAM_API_KEY=dsk_your_key_here defistream/mcp-server

Claude Desktop (Docker)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "defistream": {
      "command": "docker",
      "args": [
        "run", "-i",
        "-e", "DEFISTREAM_API_KEY=dsk_your_key_here",
        "defistream/mcp-server"
      ]
    }
  }
}

Note: Claude Desktop passes env to the spawned process, but docker run requires explicit -e flags. Put the API key in args as shown above, or set it in your shell before launching Claude Desktop.

Build from Source

cd mcp-server
docker build -t defistream/mcp-server .
docker run -i -e DEFISTREAM_API_KEY=dsk_your_key_here defistream/mcp-server

Publish to Docker Hub

docker login
docker build -t defistream/mcp-server:latest -t defistream/mcp-server:0.1.0 .
docker push defistream/mcp-server:latest
docker push defistream/mcp-server:0.1.0

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "defistream": {
      "command": "defistream-mcp",
      "env": {
        "DEFISTREAM_API_KEY": "dsk_your_key_here"
      }
    }
  }
}

Environment Variables

Variable	Required	Default	Description
DEFISTREAM_API_KEY	Yes	—	API key (dsk_xxx)
DEFISTREAM_LOCAL	No	false	Set to true to use local gateway (http://localhost:8081/v1)
DEFISTREAM_BASE_URL	No	https://api.defistream.dev/v1	API base URL (overrides DEFISTREAM_LOCAL)
DEFISTREAM_MCP_TRANSPORT	No	stdio	stdio or sse
DEFISTREAM_DOWNLOAD_DIR	No	. (cwd)	Default dir for downloaded files

Local Development

To test against the local API gateway (port 8081):

export DEFISTREAM_API_KEY="dsk_your_key"
export DEFISTREAM_LOCAL=true
defistream-mcp

Or in Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "defistream": {
      "command": "defistream-mcp",
      "env": {
        "DEFISTREAM_API_KEY": "dsk_your_key",
        "DEFISTREAM_LOCAL": "true"
      }
    }
  }
}

Tools

Utility

Tool	Description
supported_networks(protocol)	List supported networks for a protocol
supported_events(protocol)	List supported event types for a protocol
base_url()	Get the API base URL
execute_query(query, limit?)	Execute a query path and return JSON results
download_query(query, file_format?, output_dir?)	Download query results as CSV/Parquet

Protocol Query Builders

Each builder returns a query path string to pass to execute_query() or download_query().

Tool	Protocol	Required Params	Range Limits
erc20_query_builder	ERC-20 tokens	event_type, network, token	7 days / 1M blocks (10M ARB)
native_token_query_builder	Native tokens (ETH, BNB, …)	event_type, network	7 days / 1M blocks (10M ARB)
aave_v3_query_builder	AAVE V3 lending	event_type, network	31 days / 10M blocks
uniswap_v3_query_builder	Uniswap V3 DEX	event_type, network, symbol0, symbol1, fee	31 days / 10M blocks
lido_query_builder	Lido staking	event_type, network	31 days / 10M blocks
stader_query_builder	Stader ETHx	event_type, network	31 days / 10M blocks
threshold_query_builder	Threshold tBTC	event_type, network	31 days / 10M blocks

All on-chain builders also accept: block_start/block_end or since/until for range, verbose, with_value, aggregate, group_by, period, and protocol-specific filter params. JSON format is limited to 10,000 blocks for all providers.

Exchange Data Query Builders (Binance)

Tool	Data	Required Params	Range Limit
binance_raw_trades_query_builder	Raw tick trades	token	7 days
binance_ohlcv_query_builder	OHLCV candles	token	31 days
binance_book_depth_query_builder	Order book depth	token	31 days
open_interest_query_builder	Open interest	token	31 days
binance_long_short_ratios_query_builder	Long/short ratios	token	31 days
binance_funding_rate_query_builder	Funding rate	token	31 days

All exchange builders accept since/until for time range. All return CSV/Parquet only (except OHLCV which also supports JSON).

• with_value — Set true to enrich events with USD value data. Adds value_usd column to individual events, and agg_value_usd to aggregate results.

Workflow

1. supported_networks("erc20")          → check network is valid
2. erc20_query_builder(                 → build query path
     event_type="transfer",
     network="ETH",
     token="USDT",
     since="2025-01-01",
     until="2025-01-02"
   )
3. execute_query(query)                 → get JSON results
   — or —
   download_query(query, "csv")         → save CSV file

Multi-token queries: Pass comma-separated known symbol names to query multiple tokens at once (contract addresses not supported for multi-token):

erc20_query_builder(
  event_type="transfer",
  network="ETH",
  token="USDT,USDC,DAI",
  since="2025-01-01",
  until="2025-01-02"
)

Resources

URI	Description
defistream://protocols	Protocol descriptions and builder tool mapping
defistream://api-limits	Block limits, row caps, quota info

Development

pip install -e ".[dev]"
pytest