# Trading MCP Server

MCP (Model Context Protocol) server for cryptocurrency trading with Claude Desktop. Connect to MEXC, Binance, Bybit, and other exchanges via CCXT.

## Features

- **20 Trading Tools** for Claude Desktop
- **Multi-Exchange Support** via CCXT (MEXC, Binance, Bybit, OKX, and 100+ more)
- **Demo Mode** for safe testing
- **Real-time Market Data** (tickers, orderbook, OHLCV, spreads)
- **Technical Analysis** (RSI, MACD, EMA, Bollinger Bands, Stochastic)
- **Market Scanning** (spread detection, TA signals, comprehensive opportunity finder)
- **Order Management** (place, cancel, list)
- **Perpetual Futures** (leverage, positions, P&L tracking)

## Installation

```bash
npm install trading-mcp-server
```

## Quick Start

### 1. Create `.env` file

```env
EXCHANGE=mexc
MEXC_API_KEY=your_api_key
MEXC_SECRET=your_secret
TRADING_MODE=demo
MARKET_TYPE=spot
```

### 2. Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "trading": {
      "command": "npx",
      "args": ["trading-mcp-server"],
      "env": {
        "EXCHANGE": "mexc",
        "MEXC_API_KEY": "your_key",
        "MEXC_SECRET": "your_secret",
        "TRADING_MODE": "demo"
      }
    }
  }
}
```

### 3. Restart Claude Desktop

## Available Tools

### Account Tools (2)
| Tool | Description |
|------|-------------|
| `get_balance` | Get account balance (spot or futures) |
| `get_positions` | Get open futures positions with P&L |

### Market Data Tools (6)
| Tool | Description |
|------|-------------|
| `get_ticker` | Get current price for spot or perpetual pair |
| `get_multiple_tickers` | Get ticker data for multiple symbols at once |
| `get_orderbook` | Get order book depth |
| `get_ohlcv` | Get historical candlesticks (OHLCV) |
| `get_all_pairs` | Get all USDT pairs with volume and spread |
| `get_spread` | Get bid-ask spread for a pair |

### Order Tools (4)
| Tool | Description |
|------|-------------|
| `place_order` | Place spot or perpetual order (demo mode simulates) |
| `cancel_order` | Cancel an open order |
| `cancel_all_orders` | Cancel all open orders (optionally for specific symbol) |
| `get_open_orders` | List all open orders |

### Futures Tools (2)
| Tool | Description |
|------|-------------|
| `set_leverage` | Set leverage for perpetual futures (1-125x) |
| `get_leverage` | Get current leverage setting |

### Technical Analysis Tools (2)
| Tool | Description |
|------|-------------|
| `analyze_symbol_ta` | Full TA analysis (RSI, MACD, EMA, Bollinger, Stochastic) with buy/sell/hold recommendation |
| `get_indicator` | Get specific indicator (RSI, MACD, EMA, Bollinger, Stochastic, or all) |

### Market Scanning Tools (3)
| Tool | Description |
|------|-------------|
| `find_ta_signals` | Scan ALL USDT pairs for TA signals, ranked by confidence |
| `scan_spreads` | Find wide bid-ask spreads for market-making opportunities |
| `scan_best_opportunities` | Comprehensive scan combining spread, volume, and TA signals |

### System Tools (1)
| Tool | Description |
|------|-------------|
| `get_mode` | Get current trading mode (demo/live) |

**Total: 20 Tools** (2 Account + 6 Market + 4 Order + 2 Futures + 2 TA + 3 Scanner + 1 System)

## Example Prompts for Claude

### Account & Balance
```
"Show my balance"
"Show my futures balance"
"What are my open positions?"
```

### Spot Trading
```
"Get the current price of BTC/USDT"
"Show me the top 10 pairs by volume"
"What's the spread on ETH/USDT?"
"Place a $50 market buy for SOL/USDT"
```

### Perpetual Futures Trading
```
"Set 10x leverage for BTC/USDT:USDT short positions"
"Place a short order for 0.001 BTC/USDT:USDT at $90,000 with 10x leverage"
"Place a limit sell for BTC/USDT:USDT with stop loss at $91,000 and take profit at $88,000"
"Get current leverage for BTC/USDT:USDT"
```

### Technical Analysis
```
"Run technical analysis on BTC/USDT"
"Find buy signals across all USDT pairs"
"What's the RSI for ETH/USDT on the 1h timeframe?"
"Show me all indicators for SOL/USDT"
"Find the top 10 buy signals with at least 60% confidence"
```

### Market Scanning
```
"Scan for wide spreads with high volume"
"Find the best trading opportunities right now"
"Show me pairs with spreads above 0.2% and volume over 100k USDT"
"Find opportunities sorted by combined score"
```

### Multi-Timeframe Analysis
```
"Analyze BTC/USDT across multiple timeframes"
"Find pairs with strong buy signals on 15m and 1h"
```

## Trading Modes

| Mode | Description |
|------|-------------|
| `demo` | Orders are simulated (safe for testing) |
| `live` | Orders are real (use with caution) |

**Always start with `demo` mode!**

## Technical Analysis

The server includes 5 technical indicators:

| Indicator | Description | Signal Generation |
|-----------|-------------|-------------------|
| **RSI** (14) | Relative Strength Index | Oversold <35, Overbought >65 |
| **MACD** (12,26,9) | Moving Average Convergence Divergence | Crossovers and histogram |
| **EMA** (9,21) | Exponential Moving Averages | Crossovers and trend |
| **Bollinger Bands** (20,2) | Price bands based on std deviation | Position within bands |
| **Stochastic** (14,3) | Momentum oscillator | Oversold <20, Overbought >80 |

### TA Signal Confidence

The `analyze_symbol_ta` and `find_ta_signals` tools generate buy/sell recommendations based on consensus across all 5 indicators:

- **60%+ confidence** (3/5 indicators agree) = Strong signal
- **80%+ confidence** (4/5 indicators agree) = Very strong signal
- **100% confidence** (5/5 indicators agree) = Unanimous signal

## Market Scanning

### Spread Scanner
Finds pairs with wide bid-ask spreads, useful for market-making strategies.

### TA Signal Scanner
Scans all USDT pairs for technical analysis signals. Configurable:
- Signal type (buy/sell/any)
- Minimum confidence (1-100)
- Timeframe (1m, 5m, 15m, 1h, 4h, 1d)
- Volume filter
- Result limit

### Best Opportunities Scanner
Comprehensive scanner that combines:
- **Volume Score** (20%): Higher volume = better liquidity
- **Spread Score** (30%): Wider spread = more profit potential
- **TA Score** (50%): Signal confidence from technical analysis

Returns opportunities sorted by combined score, confidence, volume, or spread.

## Supported Exchanges

- MEXC
- Binance
- Bybit
- Bitget
- OKX
- And 100+ more via CCXT

## Programmatic Usage

```javascript
import { TradingMCPServer, ExchangeAdapter } from 'trading-mcp-server';

const server = new TradingMCPServer({
  exchange: 'mexc',
  apiKey: 'your_key',
  secret: 'your_secret',
  mode: 'demo',
  marketType: 'spot'
});

await server.run();
```

## Configuration

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `EXCHANGE` | Exchange name | `mexc` |
| `MEXC_API_KEY` | API key | - |
| `MEXC_SECRET` | API secret | - |
| `TRADING_MODE` | `demo` or `live` | `demo` |
| `MARKET_TYPE` | `spot` or `swap` | `spot` |
| `LOG_LEVEL` | Log level | `info` |

## Scanner Defaults

| Parameter | Default | Description |
|-----------|---------|-------------|
| `MIN_VOLUME_USDT` | 50,000 | Minimum 24h volume to analyze |
| `MAX_PAIRS` | 100 | Maximum pairs to scan |
| `MIN_CONFIDENCE` | 50 | Minimum TA signal confidence |

## Security

- **Never share your API keys**
- Use API keys **without withdrawal permission**
- Start with `demo` mode
- Set conservative limits
- Test with small amounts first

## Changelog

### v1.2.0
- Added `cancel_all_orders` tool (20 total tools)
- Added `clientOrderId` passthrough for idempotent order placement
- Improved error logging in scanner tools
- Added comprehensive `.env.example` template
- Added `.npmignore` for cleaner npm packages
- Bug fixes and stability improvements
- Added 9 new tools (19 total, up from 10)
- Technical analysis with 5 indicators
- Market scanning for spreads and TA signals
- Comprehensive opportunity finder
- Multi-symbol analysis support
- Futures positions tracking

### v1.0.0
- Initial release with 10 basic trading tools
- Spot and perpetual futures support
- Demo mode for safe testing

## License

MIT