# AsterDex MCP Server
MCP (Model Context Protocol) server for AsterDex perpetual futures market data. Provides real-time and historical market data tools for Claude Code.
## Features
### 9 Market Data Tools:
1. **get_orderbook** - Order book depth with bids and asks
2. **get_klines** - OHLCV candlestick data for technical analysis
3. **get_funding_rate_history** - Historical funding rate data
4. **get_ticker_24h** - 24-hour price statistics
5. **get_mark_price** - Mark price and funding rate info
6. **get_ticker_price** - Latest price lookup
7. **get_book_ticker** - Best bid/ask prices
8. **get_index_price_klines** - Index price history
9. **get_mark_price_klines** - Mark price history
## Installation
### Prerequisites
- Python 3.10 or higher
- Claude Code CLI
### Install the MCP Server
```bash
cd asterdex-mcp
pip install -e .
```
### Configure Claude Code
Add the server to your Claude Code MCP settings:
```bash
claude mcp add asterdex-mcp
```
Or manually add to your MCP configuration file (`~/.claude/mcp.json`):
```json
{
"mcpServers": {
"asterdex": {
"command": "python",
"args": ["-m", "asterdex_mcp.server"]
}
}
}
```
## Usage
Once installed, you can use the tools directly in Claude Code conversations:
### Example Queries
**Get BTC/USDT order book:**
```
Get the orderbook for BTCUSDT with 20 levels
```
**Get ETH price data:**
```
Show me 4-hour klines for ETHUSDT from the last 7 days
```
**Analyze funding rates:**
```
Get funding rate history for BTCUSDT over the last 30 days
```
**Check current prices:**
```
What's the current mark price and funding rate for SOLUSDT?
```
**Compare index vs mark price:**
```
Show me the difference between index price and mark price klines for BTCUSDT over the last day
```
## Available Tools
### get_orderbook
Get order book depth for a trading pair.
**Parameters:**
- `symbol` (required): Trading pair (e.g., "BTCUSDT")
- `limit` (optional): Depth limit - 5, 10, 20, 50, 100, 500, or 1000. Default: 100
**Example:**
```json
{
"symbol": "BTCUSDT",
"limit": 50
}
```
### get_klines
Get OHLCV candlestick data.
**Parameters:**
- `symbol` (required): Trading pair (e.g., "ETHUSDT")
- `interval` (required): Time interval - "1m", "5m", "15m", "30m", "1h", "4h", "1d", etc.
- `start_time` (optional): Start time in milliseconds
- `end_time` (optional): End time in milliseconds
- `limit` (optional): Number of candles (max 1500). Default: 500
**Example:**
```json
{
"symbol": "ETHUSDT",
"interval": "1h",
"limit": 100
}
```
### get_funding_rate_history
Get historical funding rate data.
**Parameters:**
- `symbol` (optional): Trading pair (returns all if not provided)
- `start_time` (optional): Start time in milliseconds
- `end_time` (optional): End time in milliseconds
- `limit` (optional): Number of records (max 1000). Default: 100
**Example:**
```json
{
"symbol": "BTCUSDT",
"limit": 50
}
```
### get_ticker_24h
Get 24-hour price change statistics.
**Parameters:**
- `symbol` (optional): Trading pair (returns all if not provided)
**Example:**
```json
{
"symbol": "SOLUSDT"
}
```
### get_mark_price
Get mark price and funding rate information.
**Parameters:**
- `symbol` (optional): Trading pair (returns all if not provided)
**Example:**
```json
{
"symbol": "BTCUSDT"
}
```
### get_ticker_price
Get latest price.
**Parameters:**
- `symbol` (optional): Trading pair (returns all if not provided)
**Example:**
```json
{
"symbol": "ETHUSDT"
}
```
### get_book_ticker
Get best bid/ask from order book.
**Parameters:**
- `symbol` (optional): Trading pair (returns all if not provided)
**Example:**
```json
{
"symbol": "BTCUSDT"
}
```
### get_index_price_klines
Get index price candlestick history.
**Parameters:**
- `pair` (required): Trading pair (e.g., "BTCUSDT")
- `interval` (required): Time interval
- `start_time` (optional): Start time in milliseconds
- `end_time` (optional): End time in milliseconds
- `limit` (optional): Number of candles (max 1500). Default: 500
**Example:**
```json
{
"pair": "BTCUSDT",
"interval": "1h",
"limit": 200
}
```
### get_mark_price_klines
Get mark price candlestick history.
**Parameters:**
- `symbol` (required): Trading pair (e.g., "BTCUSDT")
- `interval` (required): Time interval
- `start_time` (optional): Start time in milliseconds
- `end_time` (optional): End time in milliseconds
- `limit` (optional): Number of candles (max 1500). Default: 500
**Example:**
```json
{
"symbol": "BTCUSDT",
"interval": "4h",
"limit": 100
}
```
## Configuration
### Environment Variables
- `ASTERDEX_BASE_URL`: Override the API base URL (default: `https://fapi.asterdex.com`)
**Example:**
```bash
export ASTERDEX_BASE_URL=https://testnet-fapi.asterdex.com
```
## Time Format
All timestamps are in **milliseconds** since Unix epoch.
**Convert from seconds:**
```python
time_ms = time.time() * 1000
```
**Common time calculations:**
```python
import time
# Current time
now_ms = int(time.time() * 1000)
# 24 hours ago
day_ago_ms = now_ms - (24 * 60 * 60 * 1000)
# 7 days ago
week_ago_ms = now_ms - (7 * 24 * 60 * 60 * 1000)
```
## Interval Options
Valid kline intervals:
- Minutes: `1m`, `3m`, `5m`, `15m`, `30m`
- Hours: `1h`, `2h`, `4h`, `6h`, `8h`, `12h`
- Days/Weeks/Months: `1d`, `3d`, `1w`, `1M`
## Common Trading Pairs
- `BTCUSDT` - Bitcoin/USDT
- `ETHUSDT` - Ethereum/USDT
- `SOLUSDT` - Solana/USDT
- `BNBUSDT` - BNB/USDT
- `DOGEUSDT` - Dogecoin/USDT
Use the `get_ticker_price` tool without a symbol to see all available trading pairs.
## Troubleshooting
### Server not connecting
Check that the MCP server is properly installed:
```bash
claude mcp list
```
You should see `asterdex` in the list.
### Import errors
Make sure dependencies are installed:
```bash
pip install -e .
```
### API errors
The AsterDex API may have rate limits. If you encounter errors, wait a moment and try again.
## Development
### Project Structure
```
asterdex-mcp/
├── src/asterdex_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server and tools
│ ├── client.py # AsterDex API client
│ └── tools/
│ └── __init__.py
├── pyproject.toml
└── README.md
```
### Testing
Run the server directly:
```bash
python -m asterdex_mcp.server
```
## API Documentation
For detailed API documentation, see:
- [AsterDex API Documentation](https://docs.asterdex.com/product/aster-perpetuals/api/api-documentation)
- [GitHub API Docs](https://github.com/asterdex/api-docs)
## License
MIT
## Support
For issues or questions:
- GitHub: [asterdex/api-docs](https://github.com/asterdex/api-docs)
- AsterDex Docs: [docs.asterdex.com](https://docs.asterdex.com)
