# Trade MCP Server

## Overview

Trade MCP Server provides a unified interface to interact with Binance Futures (Testnet) and Aster (Mainnet) APIs using the Multi-Channel Protocol (MCP). It exposes a rich set of trading, account, and market data tools, and is designed for integration with MCP clients such as Cursor or Claude Desktop.

- Supports both Binance (Testnet) and Aster (Mainnet) via a single server.
- Exposes trading, account, and market data tools as MCP commands.
- Easily configurable for local or remote use.

---

## Quick Start

### 1. Prerequisites

- Python 3.10+
- [uv](https://github.com/astral-sh/uv) (a fast Python package manager, recommended for setup)
- Your API key and secret for either Aster or Binance Testnet

### 2. Installation

Clone the repository and install dependencies using `uv`:

```bash
git clone <repository_url>
cd trade_mcp
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
```

> If you don't have `uv` installed, get it with:
> ```bash
> pip install uv
> ```

---

## Usage

You can run the MCP server locally using the provided CLI. The server exposes all MCP tools over stdio for integration with MCP clients.

### Start the Server

```bash
trade-mcp-serve --api-key <YOUR_API_KEY> --api-secret <YOUR_API_SECRET> --provider aster
```

- For Binance Testnet, use `--provider binance --testnet`
- For Aster Mainnet, use `--provider aster` (default, no `--testnet` flag)

#### Example

```bash
trade-mcp-serve --api-key 38a9cc2dc1c8f7d867ac6c82e9cdf4671ee07321ad07d7248a11edff5f4393c3 \
  --api-secret 243ae4c25d9f2fac8e86cc38478c978c54aa12c274112cc853c07cdb5c0515d6 \
  --provider aster
```

---

## MCP Client Integration

### Cursor Example

Add the following to your `~/.cursor/mcp.json`:

```json
{
  "trade-mcp-server-local": {
    "command": "uvx",
    "args": [
      "--from",
      "trade_mcp",
      "trade-mcp-serve",
      "--api-key",
      "<YOUR_API_KEY>",
      "--api-secret",
      "<YOUR_API_SECRET>",
      "--provider",
      "aster"
    ]
  }
}
```

- Replace the API key/secret and provider as needed.

---

## Available MCP Tools

The server exposes a wide range of tools, including:

- Account and position management (`get_account_info`, `get_balance`, `get_position_mode`, etc.)
- Order management (`place_order`, `cancel_order`, `get_open_orders`, etc.)
- Market data (`get_order_book`, `get_klines`, `get_mark_price`, etc.)

See `src/trade_mcp/server/mcp_tools.py` for the full list and details.

---

## Detailed MCP Tool Descriptions

### Account and Position Management

- **get_account_info**  
  Get account information including balances and open positions.

- **get_balance**  
  Get the current futures account balance.

- **get_position_mode**  
  Get the user's position mode (Hedge Mode or One-way Mode).

- **change_position_mode**  
  Change position mode between Hedge Mode and One-way Mode.  
  Args:  
  - `dual_side`: `"true"` for Hedge Mode, `"false"` for One-way Mode

- **get_position_info**  
  Get current position information for a symbol or all symbols.

- **modify_position_margin**  
  Modify isolated position margin.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `amount`: Amount to modify  
  - `position_side`: `'BOTH'`, `'LONG'`, or `'SHORT'`  
  - `margin_type`: `1` for add, `2` for reduce

- **get_position_margin_history**  
  Get position margin modification history.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `margin_type`: `1` for add, `2` for reduce  
  - `limit`: Number of entries

- **change_leverage**  
  Change initial leverage for a symbol.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `leverage`: Target leverage (1-125)

- **change_margin_type**  
  Change margin type between isolated and cross.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `margin_type`: `'ISOLATED'` or `'CROSSED'`

- **get_leverage_brackets**  
  Get notional and leverage brackets for a symbol.

- **get_adl_quantile**  
  Get position ADL quantile estimation for a symbol.

- **get_commission_rate**  
  Get user's commission rate for a symbol.

### Order Management

- **place_order**  
  Place a futures order of any type (MARKET, LIMIT, STOP, STOP_MARKET, TRAILING_STOP_MARKET, etc).  
  Args:  
  - `symbol`, `side`, `type`, and other order parameters

- **place_multiple_orders**  
  Place multiple orders at once.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `orders`: List of order parameters (see code for details)

- **query_order**  
  Query a specific order's status.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `order_id`: Order ID

- **cancel_order**  
  Cancel an active order.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `order_id`: Order ID

- **cancel_all_orders**  
  Cancel all open orders for a symbol.  
  Args:  
  - `symbol`: Trading pair symbol

- **cancel_multiple_orders**  
  Cancel multiple orders.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `order_id_list`: List of order IDs

- **auto_cancel_all_orders**  
  Set up auto-cancellation of all orders after a countdown.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `countdown_time`: Countdown in milliseconds

- **get_open_order**  
  Query current open order by order id.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `order_id`: Order ID

- **get_open_orders**  
  Get all open futures orders for a specific symbol.  
  Args:  
  - `symbol`: Trading pair symbol

- **get_all_orders**  
  Get all account orders.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `order_id`, `start_time`, `end_time`, `limit` (optional)

- **get_account_trades**  
  Get account trade list.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `start_time`, `end_time`, `from_id`, `limit` (optional)

- **get_income_history**  
  Get income history.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `income_type`, `start_time`, `end_time`, `limit` (optional)

- **get_force_orders**  
  Get user's force orders.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `auto_close_type`, `start_time`, `end_time`, `limit` (optional)

### Market Data

- **get_order_book**  
  Get order book for a symbol.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `limit`: Number of bids/asks (5,10,20,50,100,500,1000)

- **get_aggregate_trades**  
  Get compressed, aggregate market trades.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `from_id`, `start_time`, `end_time`, `limit` (optional)

- **get_klines**  
  Get kline/candlestick data for a symbol.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `interval`: Kline interval  
  - `start_time`, `end_time`, `limit` (optional)

- **get_mark_price**  
  Get mark price and funding rate for a symbol.  
  Args:  
  - `symbol`: Trading pair symbol

- **get_funding_rate_history**  
  Get funding rate history for a symbol.  
  Args:  
  - `symbol`: Trading pair symbol  
  - `start_time`, `end_time`, `limit` (optional)

- **get_price_ticker**  
  Get latest price for a symbol.  
  Args:  
  - `symbol`: Trading pair symbol

- **get_book_ticker**  
  Get best price/qty on the order book for a symbol.  
  Args:  
  - `symbol`: Trading pair symbol

---

## Project Structure

```
.
├── src/
│   └── trade_mcp/
│       ├── api/         # Trading and market data logic
│       └── server/      # MCP server and tool setup
├── requirements.txt
├── pyproject.toml
├── Dockerfile
└── README.md
```

---

## Development & Advanced

- To run directly: `python -m trade_mcp.server.main --api-key ...`
- To build a package: `uv pip install .`
- Docker support: see `Dockerfile`, `image_build.sh`, and `image_deploy.sh`.

---

## License

MIT 