Metadata-Version: 2.4
Name: defistream-mcp
Version: 0.5.0
Summary: MCP server for the DeFiStream API
Project-URL: Homepage, https://defistream.dev
Project-URL: Documentation, https://docs.defistream.dev
Project-URL: Repository, https://github.com/Eren-Nevin/DeFiStream_MCPServer
Author-email: DeFiStream <support@defistream.dev>
License-Expression: MIT
Keywords: blockchain,defi,llm,mcp,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.7.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

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

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

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