Skip to main content
Glama
AI Trading Co-Pilot MCP Server

AI Trading Co-Pilot MCP Server

by foxisyw
README.md
#AI Trading Co-Pilot — MCP Server

AI-powered cryptocurrency trading assistant for [OpenClaw](https://openclaw.com) and any MCP-compatible client (Claude Desktop, etc.).

**4-agent analysis system** (macro + technical + risk + portfolio manager) with real-time OKX exchange integration, smart rules engine, and autonomous trading capabilities.

## ⚡ Quick Start (3 minutes)

### 1. Install

```bash
npm install @okx-trade/mcp-server
```

Or clone and install locally:
```bash
cd mcp/
npm install
```

### 2. Configure API Keys

```bash
# OKX Exchange API Key (required for trading & account data)
export OKX_DEMO_API_KEY="your-api-key"
export OKX_DEMO_SECRET_KEY="your-secret-key"
export OKX_DEMO_PASSPHRASE="your-passphrase"

# LLM API Key (required for AI analysis)
export MINIMAX_API_KEY="your-minimax-key"

# Optional settings
export OKX_MODE="demo"            # "demo" (default) or "live"
export OKX_TRADE_CONFIRM="true"   # Require confirmation before trades
```

### 3. Start the MCP Server

```bash
node bin/okx-trade-mcp.mjs
```

Or add to your MCP client config:

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "okx-trade": {
      "command": "node",
      "args": ["/path/to/mcp/bin/okx-trade-mcp.mjs"],
      "env": {
        "OKX_DEMO_API_KEY": "your-key",
        "OKX_DEMO_SECRET_KEY": "your-secret",
        "OKX_DEMO_PASSPHRASE": "your-pass",
        "MINIMAX_API_KEY": "your-minimax-key",
        "OKX_MODE": "demo"
      }
    }
  }
}
```

**OpenClaw**: Install via ClawHub or add manually in Settings → MCP Servers.

### 4. Start Chatting

```
"What's the BTC price?"
"Run a full analysis on BTC"
"Show me ETH technical analysis with 4H candles"
"Open a 10x long BTC position"
```

---

## 🔑 Configuration

### OKX API Key (Required for Trading)

1. Log in to [OKX](https://www.okx.com)
2. Go to **API Management** → Create API Key
3. Permissions needed: **Read + Trade** (do NOT enable Withdraw)
4. **Important**: Do NOT set IP whitelist (MCP runs locally with dynamic IPs)

**Demo mode** (default): Uses OKX demo trading environment — no real money involved.

| Env Variable | Description |
|---|---|
| `OKX_DEMO_API_KEY` | Demo API Key |
| `OKX_DEMO_SECRET_KEY` | Demo Secret Key |
| `OKX_DEMO_PASSPHRASE` | Demo Passphrase |
| `OKX_LIVE_API_KEY` | Live API Key (when OKX_MODE=live) |
| `OKX_LIVE_SECRET_KEY` | Live Secret Key |
| `OKX_LIVE_PASSPHRASE` | Live Passphrase |

### LLM API Key (Required for AI Analysis)

The AI co-pilot uses MiniMax M2.5 for multi-agent analysis.

1. Sign up at [MiniMax Platform](https://www.minimaxi.com)
2. Create an API Key
3. Set `MINIMAX_API_KEY` environment variable

> **Without LLM key**: Market Data, Account, Trading, and Rules tools still work. Only AI Copilot tools require the LLM key.

### Optional Settings

| Env Variable | Default | Description |
|---|---|---|
| `OKX_MODE` | `demo` | `demo` or `live` — must explicitly set `live` for real trading |
| `OKX_TRADE_CONFIRM` | `false` | `true` = always preview before executing trades |
| `DATA_DIR` | `~/.okx-trade-mcp` | Custom data directory for rules, prompts, config |

---

## 🛠 Available Tools (19)

### Market Data (4 tools) — No API key needed

| Tool | Description | Example |
|------|-------------|---------|
| `okx_get_ticker` | Real-time price, 24h change, volume | "What's the BTC price?" |
| `okx_get_candles` | OHLCV candle data (1m~1D, up to 300) | "Show me ETH 4H candles" |
| `okx_technical_analysis` | RSI, MACD, Bollinger Bands, Moving Averages | "Technical analysis for SOL" |
| `okx_get_market_data` | Open Interest, Long/Short Ratio, Funding Rate | "What's the BTC funding rate?" |

### Account (2 tools) — Requires OKX API key

| Tool | Description | Example |
|------|-------------|---------|
| `okx_get_balance` | All currencies with USD equivalent | "What's my balance?" |
| `okx_get_positions` | Open positions + PnL + leverage + margin | "Show my positions" |

### AI Analysis (3 tools) — Requires LLM key

| Tool | Description | Example |
|------|-------------|---------|
| `okx_run_copilot` | Full 4-agent analysis → signal + conviction | "Analyze BTC for me" |
| `okx_run_single_agent` | Run one agent (macro/technical/risk) | "What does the macro agent think about ETH?" |
| `okx_generate_trading_plan` | Detailed plan: entry, SL, TP, risk/reward | "Generate a trading plan" |

### Trading (2 tools) — Requires OKX API key

| Tool | Description | Example |
|------|-------------|---------|
| `okx_place_order` | Market order with leverage + SL/TP | "Open 10x long BTC, SL at 70000" |
| `okx_close_position` | Close an existing position | "Close my ETH position" |

### Rules (3 tools)

| Tool | Description | Example |
|------|-------------|---------|
| `okx_list_rules` | View all hard + soft trading rules | "List my rules" |
| `okx_evaluate_rules` | Check if a trade passes hard rules | "Can I go long BTC now?" |
| `okx_add_rule` | Add rule via natural language | "Block trades when funding > 0.1%" |

### Skills & Config (5 tools)

| Tool | Description | Example |
|------|-------------|---------|
| `okx_list_skills` | View 6 analysis skills and status | "What skills are available?" |
| `okx_configure_skills` | Enable/disable skills per agent | "Enable fibonacci for technical agent" |
| `okx_get_prompts` | View agent system prompts | "Show me the current prompts" |
| `okx_update_prompt` | Customize an agent's prompt | "Make technical agent focus on volume" |
| `okx_set_llm_config` | Configure temperature, max tokens | "Set temperature to 0.3" |

---

## 💬 Usage Examples

### Market Analysis
```
"What's the current BTC price and 24h change?"
"Show me ETH technical analysis with 4H candles"
"What's the current funding rate for BTC?"
"Get the open interest and long/short ratio for SOL"
```

### AI Co-Pilot
```
"Run a full analysis on BTC"
"What does the macro agent think about ETH?"
"Run technical analysis only for SOL"
"Generate a trading plan based on the analysis"
```

### Trading
```
"Open a 10x long BTC position with 10 contracts"
"Place a short ETH order with SL at 4000 and TP at 3500"
"Close my BTC-USDT-SWAP position"
"Show my current positions and P&L"
```

### Rules Management
```
"Add a rule: block all trades when funding rate > 0.1%"
"Add a rule: don't go long when L/S ratio > 2"
"List my trading rules"
"Check if a BTC long trade would pass my rules"
```

### Customization
```
"Show me the current agent prompts"
"Update the technical agent prompt to focus more on volume analysis"
"Enable fibonacci and candlestick-patterns skills for technical agent"
"Disable the fear-greed-index skill"
"Set LLM temperature to 0.3"
```

---

## 🤖 AI Agents

The co-pilot runs 4 AI agents:

| Agent | Role | Focus |
|-------|------|-------|
| 🌐 **Macro Analyst** | Macro environment | Fed policy, DXY, ETF flows, on-chain data |
| 📊 **Technical Analyst** | Chart analysis | RSI, MACD, Bollinger Bands, trend, key levels |
| 🛡️ **Risk Manager** | Risk assessment | Position sizing, leverage, stop-loss, max risk |
| 👔 **Portfolio Manager** | Final decision | Synthesizes all reports → LONG/SHORT/HOLD + conviction |

**Workflow**: Macro + Technical + Risk run in parallel → Portfolio Manager synthesizes → Final signal

---

## ⚙️ Analysis Skills (6)

| Skill | Description | Agents |
|-------|-------------|--------|
| `fibonacci-levels` | Fibonacci retracement from swing H/L | Technical, Manager |
| `candlestick-patterns` | Doji, Engulfing, Hammer detection | Technical, Manager |
| `volume-profile` | Volume distribution + POC | Technical, Risk |
| `orderflow-analysis` | OI changes, L/S ratio trends | Technical, Risk, Manager |
| `volatility-regime` | Classify Low/Normal/High/Extreme | Risk, Manager |
| `fear-greed-index` | Crypto market sentiment (0-100) | Macro, Manager |

All skills are enabled by default. Use `okx_configure_skills` to customize.

---

## 🎨 Canvas Dashboard

For OpenClaw users, two HTML templates are included for visual rendering:

- **`dashboard.html`** — Main trading dashboard (price, positions, signal, chart)
- **`analysis-report.html`** — Full analysis report (agent cards, trading plan, reasoning)

Ask the agent: *"Show me the dashboard"* or *"Render the analysis report"*

---

## 📋 Supported Instruments

| Instrument | SWAP | SPOT |
|------------|------|------|
| BTC-USDT | ✅ | ✅ |
| ETH-USDT | ✅ | ✅ |
| SOL-USDT | ✅ | ✅ |
| OKB-USDT | ✅ | ✅ |

---

## 🔒 Security

- ✅ **All API keys stay local** — stored in environment variables, never transmitted
- ✅ **Zero hardcoded credentials** — npm package contains no secrets
- ✅ **Tool responses never include API keys** — all sensitive data stripped
- ✅ **Default demo mode** — must explicitly opt-in to live trading
- ✅ **Trade confirmation** — optional preview before execution
- ✅ **No third-party data sharing** — only connects to OKX API and LLM provider
- ✅ **Hard rules auto-enforcement** — programmatic blocks cannot be bypassed

---

## 🔧 Testing

### MCP Inspector
```bash
npx @modelcontextprotocol/inspector node bin/okx-trade-mcp.mjs
```

### Claude Desktop
Add to `claude_desktop_config.json` and restart Claude Desktop.

### OpenClaw
Install the plugin from ClawHub or add as custom MCP server.

---

## 📄 License

MIT

---

## 🌐 Links

- [OKX API Documentation](https://www.okx.com/docs-v5/)
- [MCP Protocol Specification](https://modelcontextprotocol.io)
- [OpenClaw Platform](https://openclaw.com)
- [MiniMax API](https://www.minimaxi.com)

TDQS

A3.8/5.0

Scored across 19 tools

Disambiguation4/5

Each tool targets a distinct resource/action (market data, account, orders, AI agents, rules, skills, prompts). The only potential confusion is between get_ticker and get_market_data, but the latter is derivatives-specific and the former covers all instruments. Overall clear separation.

Naming Consistency5/5

All tools share the okx_ prefix and use verb_noun (or verb_adj_noun) structure consistently, e.g., get_candles, place_order, list_rules, update_prompt. The single exception is technical_analysis which lacks a verb but is still readable. Pattern is predictable and easy to navigate.

Tool Count4/5

19 tools is on the heavier side but justified by the breadth of the domain: market data, account management, trading execution, AI agents, rules, skills, and configuration. Each tool maps to a distinct feature, so the count is appropriate for a comprehensive trading copilot.

Completeness4/5

Core trading lifecycle is covered: market data, analysis, balance, positions, place/close orders. The rule-based risk system and AI agent customization add depth. Missing order history and cancel order, but these are secondary gaps that don't break the core workflow.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues