BitUnix Trading MCP Server

A powerful Model Context Protocol (MCP) server that provides a bridge between Claude Code and the BitUnix Exchange API. It supports both Futures and Spot trading with advanced order management.

✨ Features

📈 Futures Trading

• Order Placement: Market and Limit orders with hedge mode support.
• Leverage & Margin: Set leverage and margin mode (Isolated/Cross) per symbol.
• Position Management: Close positions, flash-close (emergency exit), and monitor PnL.
• Batch Orders: Execute up to 5 orders for the same symbol in a single call.

🛡️ Advanced TP/SL

• Precise Control: Set Take Profit and Stop Loss with specific trigger types (Mark/Last Price).
• Modification Workaround: Includes an internal "Cancel + Re-place" logic to bypass BitUnix API limitations, ensuring reliable TP/SL updates.

💰 Spot Trading & Conversion

• Spot Wallet: Full access to spot balances and trading pairs.
• Auto-Conversion: A unique convert_currency tool that automates the transfer between Futures and Spot wallets to convert assets (e.g., USDC ↔ USDT) in one step.

🛠️ Installation

Prerequisites

• Node.js: Used for the MCP bridge wrapper.
• Python 3.10+: Used for the core logic (FastMCP).
• BitUnix API Keys: Required for private operations.

Setup

1. Open the .env file and enter your API keys.
   • Where to get keys? Log in to your BitUnix account and go to: https://www.bitunix.com/account/apiManagement
   • Manual path: Hover over your Profile Icon (top-right) -> Click "API"
2. Enter your BITUNIX_API_KEY and BITUNIX_SECRET_KEY in the file.
3. Install Python dependencies:

   pip install -r requirements.txt
   

🚀 Usage

Claude Code Configuration

Add the server to your .mcp.json file. Ensure the path to index.js is correct:

{
  "mcpServers": {
    "bitunix": {
      "command": "node",
      "args": ["./Bitunix-trading-mcp/index.js"]
    }
  }
}

Manual Startup (for Testing)

You can start the server manually to verify it's working:

node index.js

Upon startup, the server will output its status to stderr, including the Python path and process ID. It will then wait for MCP JSON-RPC messages on stdin.

Key Tools & Examples

• get_account: Check your available balance.
• place_order: Open a new position.
• place_tpsl_order: Set protection for an open position.
• convert_currency: Move and convert funds between wallets.

Example Tool Call (JSON-RPC):

{
  "method": "tools/call",
  "params": {
    "name": "get_account",
    "arguments": { "margin_coin": "USDT" }
  }
}

⚙️ How it Works (Architecture)

The server uses a dual-layer architecture:

1. Node.js Wrapper (index.js): Acts as the entry point for Claude Code. It searches for a valid Python executable on your system, loads environment variables from .env, and spawns the Python process.
2. Python Core (main.py): Uses the FastMCP framework to define and register trading tools. It handles the actual API communication with BitUnix using the BitunixClient class.

❓ Troubleshooting

1. Python not found

The Node wrapper tries to find python3, python, or py. If it fails, ensure Python is in your system's PATH. You can check what the server is using by looking at the terminal output: Python: C:\Path\To\python.exe

2. API Errors (Code 2, 10002, etc.)

• Error 10002: Often caused by trying to set leverage/margin inside an order call. The server requires you to set these separately first.
• Error 2: Usually means a required parameter is missing or formatted incorrectly.

3. Connection Issues

Ensure your .env file is in the Bitunix-trading-mcp directory and contains valid keys. The server will output a warning if the .env file cannot be read.

🔒 Security

• Environment Variables: Sensitive keys are loaded from .env and are excluded from Git via .gitignore.
• Hedge Mode: The server defaults to Hedge Mode (separate Long/Short) as required by professional trading standards.

📄 License

MIT