mbrio089/kucoin-mcp-server

KuCoin Futures MCP Server

A production-ready Model Context Protocol (MCP) Server for KuCoin Futures API with header-based authentication, deployed on Vercel Edge Functions.

📑 Table of Contents

• Features
• Quick Start
• Prerequisites
• Deployment
• Usage
• API Reference
• Architecture
• Security
• Troubleshooting
• Contributing
• License

🚀 Features

20 Complete Trading Tools

Key Capabilities

• ✅ Real-time Trading - Place, cancel, and monitor orders
• ✅ Position Management - Track P&L, manage margin, view history
• ✅ Risk Management - Stop-loss and take-profit orders
• ✅ Market Analysis - OHLCV data, order book depth, funding rates
• ✅ Universal Compatibility - Claude Desktop, n8n, direct HTTP
• ✅ Production Ready - European deployment, rate limiting, error handling

🚀 Quick Start

1. Get KuCoin API Keys

# Visit https://futures.kucoin.com/api
# Create API key with permissions: General, Trade

2. Deploy to Vercel

3. Configure Environment Variables

KUCOIN_API_KEY=your_api_key
KUCOIN_API_SECRET=your_api_secret
KUCOIN_API_PASSPHRASE=your_passphrase
MCP_AUTH_KEY=your_secure_auth_key

4. Connect to Claude Desktop

{
  "mcpServers": {
    "kucoin-futures": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-deployment.vercel.app/mcp"],
      "env": {}
    }
  }
}

📋 Prerequisites

Required Accounts

1. KuCoin Futures Account

   • API key with General and Trade permissions
   • Sufficient balance for trading operations

2. Vercel Account

   • For deploying the MCP server
   • Free tier sufficient for personal use

Supported Clients

• Claude Desktop - Direct MCP integration
• n8n Workflows - HTTP Request nodes
• Custom Applications - Direct JSON-RPC API

🚀 Deployment

Option 1: One-Click Deploy (Recommended)

Option 2: Manual Deployment

1. Clone Repository

   git clone https://github.com/mbrio089/kucoin-mcp-server.git
   cd kucoin-mcp-server
   

2. Install Vercel CLI

   npm i -g vercel
   

3. Deploy

   vercel --prod
   

4. Set Environment Variables

   vercel env add KUCOIN_API_KEY
   vercel env add KUCOIN_API_SECRET
   vercel env add KUCOIN_API_PASSPHRASE
   vercel env add MCP_AUTH_KEY
   

Environment Configuration

Copy .env.example to configure your deployment:

# KuCoin Futures API credentials (get from https://futures.kucoin.com/api)
KUCOIN_API_KEY=your_kucoin_api_key_here
KUCOIN_API_SECRET=your_kucoin_api_secret_here
KUCOIN_API_PASSPHRASE=your_kucoin_api_passphrase_here

# MCP Authentication (generate a secure random string)
MCP_AUTH_KEY=your_secure_mcp_auth_key_here

🛠️ Usage

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "kucoin-futures": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-deployment.vercel.app/mcp"],
      "env": {}
    }
  }
}

Example Prompts:

"Show me all available futures contracts"
"What's the current price of XBTUSDTM?"
"Place a limit buy order for 0.1 BTC at $65000"
"Show my current positions and their P&L"
"Set a stop loss at $60000 for my BTC position"

n8n Workflow Integration

Use HTTP Request nodes with authentication:

{
  "method": "POST",
  "url": "https://your-deployment.vercel.app/mcp",
  "headers": {
    "Content-Type": "application/json",
    "X-MCP-Auth-Key": "your-auth-key"
  },
  "body": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "getPositions",
      "arguments": {}
    }
  }
}

Direct HTTP API

curl -X POST https://your-deployment.vercel.app/mcp \
  -H "Content-Type: application/json" \
  -H "X-MCP-Auth-Key: your-auth-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "getTicker",
      "arguments": {"symbol": "XBTUSDTM"}
    }
  }'

📖 API Reference

Authentication

Two authentication methods supported:

# Method 1: Custom Header
X-MCP-Auth-Key: your-auth-key

# Method 2: Bearer Token
Authorization: Bearer your-auth-key

Tool Categories

⚡ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │    │  Vercel Edge    │    │  KuCoin API     │
│  (Claude/n8n)  │◄──►│   Functions     │◄──►│    Futures      │
│                 │    │   (EU Regions)  │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Technical Stack

• Runtime: Vercel Edge Functions (Node.js 22.x)
• Language: TypeScript with Zod validation
• Protocol: JSON-RPC 2.0 compliant MCP
• Deployment: European regions (Frankfurt, Dublin, Paris)
• Authentication: HMAC SHA256 + Header-based MCP auth

Key Benefits

• Low Latency: Edge functions with <100ms response times
• Geo-Bypass: European deployment avoids US restrictions
• Scalability: Auto-scaling without infrastructure management
• Security: Multi-layer authentication and encrypted transmission

🔒 Security

Multi-Layer Security

1. Transport Security: HTTPS/TLS encryption
2. API Authentication: HMAC SHA256 signatures for KuCoin
3. Access Control: Header-based authentication for MCP
4. Input Validation: Zod schemas validate all inputs
5. Environment Security: Sensitive data in Vercel environment variables

Rate Limiting

• Market Data: 100 requests/10 seconds
• Trading: 30 requests/3 seconds
• Individual Endpoints: Specific limits per endpoint

Best Practices

• Never commit API keys to version control
• Use environment variables for all sensitive data
• Regularly rotate authentication keys
• Monitor API usage and rate limits

🔧 Troubleshooting

Common Issues

401 Authentication Errors

# Check MCP authentication
curl -H "X-MCP-Auth-Key: your-key" https://your-deployment.vercel.app/mcp

# Verify environment variables in Vercel dashboard
vercel env ls

KuCoin API Errors

• Verify API key permissions (General + Trade required)
• Check rate limits (Market: 100/10s, Trading: 30/3s)
• Ensure correct API credentials in environment variables

Geo-restriction Issues

• Server deployed in EU regions to bypass US restrictions
• If issues persist, check deployment region in Vercel

Tool Execution Errors

• Validate JSON-RPC request format
• Ensure all required parameters are provided
• Check tool schemas in MCP tools list

Debug Commands

# Test MCP server health
curl -X OPTIONS https://your-deployment.vercel.app/mcp

# List available tools
curl -X POST https://your-deployment.vercel.app/mcp \
  -H "Content-Type: application/json" \
  -H "X-MCP-Auth-Key: your-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Check Vercel deployment logs
vercel logs https://your-deployment.vercel.app

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/mbrio089/kucoin-mcp-server.git
cd kucoin-mcp-server
npm install
cp .env.example .env.local  # Configure your environment
vercel dev  # Start local development server

Code Standards

• TypeScript with strict mode
• Zod for input validation
• JSON-RPC 2.0 compliance
• Comprehensive error handling

📄 License

This project is licensed under the MIT License - see the file for details.

Author

Moritz Braun LinkedIn: https://www.linkedin.com/in/moritz-braun-748434b4/

⭐ Star this repository if you find it helpful!

Need help? Open an issue or check the troubleshooting guide.