# MCP-Server-Aster-DEX
MCP server for Aster DEX — a Model Context Protocol server that gives Claude, Cursor and Cline structured access to Aster DEX market data, volume, points and airdrop eligibility via natural language. Read-only tools — no trading, no keys. Unofficial community project, not affiliated with Aster.
<div align="center">

# 🔌 MCP Server — Aster DEX

### MCP server for Aster DEX — volume, points, rank & airdrop eligibility as tools for LLM agents.

[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-7C3AED.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Aster](https://img.shields.io/badge/Aster-DEX-F0B90B.svg)](https://aster.finance/)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](./README.md)

**Ask Claude / Cline / Cursor: *"What's left for my Aster wallet to qualify for GOLD?"* — and get a real answer.**

</div>

---

## 📖 Overview

**MCP Server — Aster DEX** is a **Model Context Protocol server for the Aster DEX API** that
exposes trading volume, points, leaderboard rank and airdrop eligibility as **MCP tools** for
any MCP-compatible LLM agent. It **gives Claude, Cursor, and Cline access to Aster DEX
market data** through natural language — a **BNB Chain perp DEX integration for LLM
agents**, **built on the official Model Context Protocol Python SDK**.

Instead of refreshing a web dashboard, your AI assistant calls the tools directly and reasons
about your Aster farming progress in plain language — **query volume, points, and airdrop
stats from your AI assistant**, with **structured JSON responses for agent workflows**:

> *"You're at $161,400 campaign volume — SILVER tier, 7% into the next tier. Keep your
> streak alive (12 days now) and provide liquidity for 30 days to also satisfy the
> liquidity criterion for GOLD."*

> ⚠️ **Read-only tools — no trading, no private keys required.** The server exposes data
> tools only; it cannot place orders.

---

## ✨ Tools exposed

| Tool | Returns |
|------|---------|
| `get_volume` | Today / 7-day / 30-day / campaign volume + streak. |
| `get_points` | Estimated points with streak bonus breakdown. |
| `get_rank` | Leaderboard position with daily delta. |
| `get_markets` | Available Aster trading pairs. |
| `get_eligibility` | Airdrop tier snapshot — satisfied vs. missing criteria. |
| `list_tasks` | Farming task checklist with completion state. |

Each tool returns typed JSON the agent can reason over.

---

## 🚀 Quick start

```bash
git clone https://github.com/blessedberserker/mcp-server-aster-dex.git
cd mcp-server-aster-dex
pip install -r requirements.txt

python main.py --demo      # stdio transport, bundled demo wallet
```

Or use the one-click launchers (they unpack a bundled standalone interpreter on first run):

```batch
run.bat        :: Windows
```
```bash
chmod +x run.sh && ./run.sh    # Linux / macOS
```

## 🔌 Connect your client

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "aster": {
      "command": "python",
      "args": ["C:\\path\\to\\mcp-server-aster-dex\\main.py", "--demo"]
    }
  }
}
```

### Cline / Cursor / Continue
Point the client at the server over stdio with the same command. One-line install per client —
see your client's MCP settings page.

---

## 🧪 Try the tools headlessly

```bash
python main.py --tool get_eligibility --demo
python main.py --tool get_points --wallet 0x42…aa91 --demo
```

---

## 🗂️ Project layout

```
mcp-server-aster-dex/
├── main.py               # Entry point (unpacks bundled runtime on first launch)
├── mcp_aster/            # Host package
│   ├── __main__.py       # `python -m mcp_aster` entry (argparse + server bootstrap)
│   ├── server.py         # FastMCP tool definitions
│   ├── config.py         # Config loader (TOML)
│   └── core/             # models, analytics, mock data
├── kernel/               # Runtime support library
├── requirements.txt
├── run.bat / run.sh      # One-click launchers
└── release/              # Pre-compiled binaries (planned)
```

---

## ⚙️ Configuration

```toml
# ~/.aster-mcp/config.toml
[network]
rpc_bnb  = "https://bsc-dataseed.binance.org"
rpc_base = "https://mainnet.base.org"

[campaign]
points_per_dollar    = 2.0
streak_bonus_per_day = 0.05
max_streak_bonus     = 0.50
tiers = [
    { name = "BRONZE",   volume = 50000 },
    { name = "SILVER",   volume = 150000 },
    { name = "GOLD",     volume = 300000 },
    { name = "PLATINUM", volume = 600000 },
]
```

---

## 🔒 Security

- **Read-only.** Data tools only — no order placement, no signing, no private keys.
- **No telemetry.** Queries go to the configured public RPCs.

---

## ❓ FAQ

<details>
<summary><b>What is MCP?</b></summary>

The Model Context Protocol — an open standard for connecting LLMs to external tools and
data sources. See [modelcontextprotocol.io](https://modelcontextprotocol.io/).
</details>

<details>
<summary><b>Does the server trade on my behalf?</b></summary>

No. Read-only data tools. An LLM can summarise your farming progress, but it cannot place
orders through this server.
</details>

<details>
<summary><b>Is this affiliated with Aster or Anthropic?</b></summary>

No. Independent, unofficial community project. Aster is a third-party protocol; MCP is an
open standard.
</details>

---

## ⚠️ Disclaimer

This is an **unofficial community project**, **not affiliated with, endorsed by, or
sponsored by Aster Finance or Anthropic**. Provided for research purposes — **not financial
advice**.

---

## 📄 License

MIT — see [`LICENSE`](./LICENSE).

<div align="center"><sub>Bring Aster DEX data into your LLM agent.</sub></div>