defistream-mcp 0.2.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
DEFISTREAM_QUERY_ROW_LIMIT	No	200	Max rows returned by execute_query

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
erc20_query_builder	ERC-20 tokens	event_type, network, token
native_token_query_builder	Native tokens (ETH, BNB, …)	event_type, network
aave_v3_query_builder	AAVE V3 lending	event_type, network
uniswap_v3_query_builder	Uniswap V3 DEX	event_type, network, symbol0, symbol1, fee
lido_query_builder	Lido staking	event_type, network
stader_query_builder	Stader ETHx	event_type, network
threshold_query_builder	Threshold tBTC	event_type, network

All builders also accept: block_start/block_end or since/until for range, verbose, with_value, aggregate, group_by, period, and protocol-specific filter params.

• 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