MCP Bitget Trading Server

Instructions

Implementation Reference

• src/server.ts:353-364 (handler)

  MCP server handler for getCandles tool: parses arguments using schema, calls BitgetRestClient.getCandles, returns JSON stringified candles data.

  case 'getCandles': {
    const { symbol, interval, limit = 100 } = GetCandlesSchema.parse(args);
    const candles = await this.bitgetClient.getCandles(symbol, interval, limit);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(candles, null, 2),
        },
      ],
    } as CallToolResult;
  }

• src/types/mcp.ts:22-35 (schema)

  Zod schema definition for getCandles tool input parameters: symbol, interval (enum), optional limit.

  export const GetCandlesSchema = z.object({
    symbol: z.string().describe('Trading pair symbol (BTCUSDT for spot, BTCUSDT_UMCBL for futures)'),
    interval: z.enum([
      // Minutes (lowercase)
      '1m', '3m', '5m', '15m', '30m',
      // Hours (can be lowercase, will be converted)
      '1h', '4h', '6h', '12h', '1H', '4H', '6H', '12H',
      // Days/Weeks/Months (can be lowercase, will be converted)
      '1d', '1w', '1D', '1W', '1M',
      // UTC variants
      '6Hutc', '12Hutc', '1Dutc', '3Dutc', '1Wutc', '1Mutc'
    ]).describe('Candle interval - API will auto-format to correct case'),
    limit: z.number().optional().describe('Number of candles (default: 100)')
  });

• src/server.ts:137-148 (registration)

  Tool registration in MCP server's listTools response: defines name, description, and inputSchema for getCandles.

  {
    name: 'getCandles',
    description: 'Get historical candlestick/OHLCV data',
    inputSchema: {
      type: 'object',
      properties: {
        symbol: { type: 'string', description: 'Trading pair symbol' },
        interval: { type: 'string', enum: ['1m', '5m', '15m', '30m', '1h', '4h', '1d'], description: 'Candle interval' },
        limit: { type: 'number', description: 'Number of candles (default: 100)' }
      },
      required: ['symbol', 'interval']
    },

• src/api/rest-client.ts:465-512 (helper)

  Core implementation of getCandles in BitgetRestClient: handles spot and futures candles via Bitget v2 API, formats intervals appropriately, maps raw API data to Candle[] type.

  async getCandles(symbol: string, interval: string, limit: number = 100): Promise<Candle[]> {
    if (this.isFuturesSymbol(symbol)) {
      // Futures candles - use v2 API with productType
      // Remove _UMCBL suffix if present for v2 API
      const cleanSymbol = symbol.replace('_UMCBL', '');
      const response = await this.request<string[][]>('GET', '/api/v2/mix/market/candles', {
        productType: 'USDT-FUTURES',
        symbol: cleanSymbol,
        granularity: this.formatIntervalForFuturesAPI(interval), // Format interval for futures API
        limit: limit.toString()
      });
  
      if (!response.data || response.data.length === 0) {
        return [];
      }
  
      return response.data.map(candle => ({
        symbol: symbol, // Keep original symbol format
        timestamp: parseInt(candle[0]),
        open: candle[1],
        high: candle[2],
        low: candle[3],
        close: candle[4],
        volume: candle[5]
      }));
    } else {
      // Spot candles
      const response = await this.request<string[][]>('GET', '/api/v2/spot/market/candles', {
        symbol,
        granularity: this.formatIntervalForSpotAPI(interval), // Format interval for spot API
        limit: limit.toString()
      });
  
      if (!response.data || response.data.length === 0) {
        return [];
      }
  
      return response.data.map(candle => ({
        symbol,
        timestamp: parseInt(candle[0]),
        open: candle[1],
        high: candle[2],
        low: candle[3],
        close: candle[4],
        volume: candle[5]
      }));
    }
  }