# Dune MCP Server

A comprehensive MCP (Model Context Protocol) server for interacting with [Dune Analytics](https://dune.com/) - the leading platform for blockchain data analysis.

## Features

### Tools

This server exposes all major Dune Analytics API endpoints as MCP tools:

#### SQL Execution
- `execute_sql` - Execute raw SQL queries against Dune's data engine
- `get_execution_status` - Check query execution status
- `get_execution_results` - Retrieve query results (JSON)
- `get_execution_results_csv` - Retrieve query results (CSV)
- `cancel_execution` - Cancel a running query

#### Saved Query Management
- `execute_query` - Execute a saved query by ID
- `get_query` - Get query details
- `get_query_results` - Get latest cached results without re-executing
- `get_query_results_csv` - Get latest results as CSV
- `create_query` - Create and save a new query
- `update_query` - Update an existing query
- `archive_query` - Archive a query
- `make_query_private` / `make_query_public` - Change query visibility

#### Data Upload
- `upload_csv` - Upload CSV data to create/update a table
- `create_table` - Create a new table with schema
- `insert_table_rows` - Insert rows into an existing table
- `clear_table` - Clear all data from a table
- `delete_table` - Permanently delete a table

### Resources

The server exposes comprehensive documentation as MCP resources to help LLMs write valid DuneSQL queries:

| Resource URI | Description |
|--------------|-------------|
| `dune://guide/sql-syntax` | DuneSQL (Trino) syntax reference, data types, functions |
| `dune://guide/tables` | Available tables: dex.trades, prices.usd, chain-specific tables |
| `dune://guide/query-patterns` | Common analytics patterns: volume, holders, whales, gas |
| `dune://guide/parameters` | How to use query parameters |
| `dune://guide/errors` | Common errors and troubleshooting |

## Installation

```bash
cd dune-mcp
pip install -e .
```

## Configuration

Set your Dune API key as an environment variable:

```bash
export DUNE_API_KEY="your-api-key-here"
```

Get your API key from [Dune Settings](https://dune.com/settings/api).

## Usage

### Running the Server

```bash
# Direct execution
python server.py

# Or via installed script
dune-mcp
```

### Claude Desktop Configuration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "dune": {
      "command": "python",
      "args": ["/path/to/dune-mcp/server.py"],
      "env": {
        "DUNE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Or using uv:

```json
{
  "mcpServers": {
    "dune": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/dune-mcp", "python", "server.py"],
      "env": {
        "DUNE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Example Queries

### Simple DEX Volume Query

```python
# Using execute_sql tool
result = await execute_sql(
    sql="""
    SELECT 
        project,
        SUM(amount_usd) as volume
    FROM dex.trades
    WHERE block_time > now() - interval '24' hour
    GROUP BY 1
    ORDER BY 2 DESC
    LIMIT 10
    """,
    performance="medium"
)
```

### Cross-Chain Analysis

```python
result = await execute_sql(
    sql="""
    SELECT 
        blockchain,
        COUNT(*) as tx_count,
        SUM(amount_usd) as volume_usd
    FROM dex.trades
    WHERE block_time > now() - interval '7' day
    GROUP BY 1
    ORDER BY 3 DESC
    """
)
```

### Create Parameterized Query

```python
result = await create_query(
    name="Token Volume Analysis",
    query_sql="""
    SELECT 
        DATE_TRUNC('day', block_time) as day,
        SUM(amount_usd) as volume
    FROM dex.trades
    WHERE token_bought_symbol = '{{token}}'
        AND block_time > now() - interval '{{days}}' day
    GROUP BY 1
    ORDER BY 1
    """,
    parameters=[
        {"key": "token", "value": "UNI", "type": "text"},
        {"key": "days", "value": "30", "type": "number"}
    ]
)
```

## Available Tables

### Curated (Cross-Chain)
- `dex.trades` - DEX trades across all EVM chains
- `dex_solana.trades` - Solana DEX trades
- `nft.trades` - NFT trades
- `prices.usd` - Token prices
- `tokens.erc20` - ERC20 token metadata

### Chain-Specific
- `ethereum.transactions`, `ethereum.logs`, `ethereum.traces`
- `polygon.transactions`, `polygon.logs`, etc.
- `arbitrum.transactions`, `optimism.transactions`, `base.transactions`

### Decoded Protocol Tables
- `uniswap_v3_ethereum.Pair_evt_Swap`
- `aave_v3_ethereum.Pool_evt_Supply`
- And many more...

## API Reference

See [Dune API Documentation](https://docs.dune.com/api-reference) for complete API details.

## License

MIT