defistream-mcp 0.5.0

MCP server for the DeFiStream API

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