# DEX K-line MCP

An MCP server that streams K-line (candlestick) data from decentralized exchanges (DEXs) to power your AI agents and workflows.

## Features

- **K-line Data Retrieval**: Fetches OHLCV (Open, High, Low, Close, Volume) data for specified tokens on supported chains (Ethereum, Binance Smart Chain, Solana).
- **Dynamic Timeframes**: Supports multiple timeframes (`1m`, `5m`, `15m`, `1h`, `4h`, `12h`, `1d`) with appropriate API endpoints.
- **Best Pool Selection**: Automatically selects the pool with the highest liquidity for accurate data.
- **Flexible End Time**: Allows specifying an end time in ISO 8601 format or defaults to the current UTC time.
- **Tabular Output**: Formats K-line data into a clean, readable table using the `tabulate` library.

## Installation

### Prerequisites

- Python 3.10 or higher
- [uv](https://github.com/astral-sh/uv) for dependency management

### Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/kukapay/dex-kline-mcp.git
   cd dex-kline-mcp
   ```

2. Install dependencies:
   ```bash
   uv sync
   ```

3. **Installing to Claude Desktop**:

    Install the server as a Claude Desktop application:
    ```bash
    uv run mcp install main.py --name "DEX K-line"
    ```

    Configuration file as a reference:

    ```json
    {
       "mcpServers": {
           "DEX K-line": {
               "command": "uv",
               "args": [ "--directory", "/path/to/dex-kline-mcp", "run", "main.py" ]
           }
       }
    }
    ```
    Replace `/path/to/dex-kline-mcp` with your actual installation path.

## Usage

### Tool: `get_kline`

The server exposes a single tool, `get_kline`, which retrieves K-line data for a specified token.

#### Parameters
- `chain` (str): Blockchain network (e.g., `eth`, `bsc`, `solana`)
- `address` (str): Token contract address
- `timeframe` (str): K-line timeframe (e.g., `1m`, `5m`, `15m`, `1h`, `4h`, `12h`, `1d`). Default: `1h`
- `end_time` (str, optional): ISO 8601 timestamp for data end time (e.g., `2025-07-03T02:14:00Z`). Default: current UTC time
- `limit` (int): Number of data points to return (max 1000). Default: 100

#### Example Prompt
> Fetch the 1-hour K-line data for the token with the contract address 0xf4b385849f2e817e92bffbfb9aeb48f950ff4444 on the Binance Smart Chain (BSC). 

#### Example Output
```
Pair: TOKEN/USDT

+---------------------+------------+------------+------------+------------+------------+
| Timestamp           | Open       | High       | Low        | Close      | Volume     |
+---------------------+------------+------------+------------+------------+------------+
| 2025-07-03 01:00:00 | 0.12345678 | 0.12345678 | 0.12345678 | 0.12345678 | 1234.56789 |
| 2025-07-03 00:00:00 | 0.12345678 | 0.12345678 | 0.12345678 | 0.12345678 | 1234.56789 |
+---------------------+------------+------------+------------+------------+------------+
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Acknowledgments

Data powered by [GeckoTerminal API](https://www.geckoterminal.com).