defistream-mcp 0.2.0
MCP server for the DeFiStream API
Requires Python: >=3.10
Keywords: blockchain, defi, llm, mcp, model-context-protocol

# DeFiStream MCP Server

Model Context Protocol (MCP) server that wraps the [DeFiStream](https://defistream.dev) 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

```bash
# 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:

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

### Claude Code

```bash
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`:

```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

```bash
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

```bash
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`:

```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):

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

Or in Claude Desktop / Claude Code config:

```json
{
  "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

```bash
pip install -e ".[dev]"
pytest
```