Binance MCP Server

Instructions

Implementation Reference

• src/connectors/binance-rest.ts:189-213 (handler)

  Core implementation of the get_klines tool. Fetches historical candlestick (kline) data from Binance REST API for spot or futures markets. Uses axios with retry logic via executeWithRetry, handles parameters and returns raw API response data.

  public async getKlines(
    symbol: string,
    type: 'spot' | 'futures',
    interval: string,
    limit?: number
  ): Promise<any> {
    try {
      logger.info(`Getting ${type} klines for ${symbol}`);
      const baseUrl = type === 'spot' ? config.SPOT_REST_URL : config.FUTURES_REST_URL;
      const response = await this.executeWithRetry(() =>
        this.axiosInstance.get(`${baseUrl}/klines`, {
          params: {
            symbol: symbol.toUpperCase(),
            interval,
            limit: limit || 500
          }
        })
      );
      logger.info('Successfully fetched klines data');
      return response.data;
    } catch (error) {
      logger.error('Error fetching klines:', error);
      throw new APIError('Failed to fetch klines data', error as Error);
    }
  }

• src/index.ts:108-135 (registration)

  Registers the get_klines tool with the MCP server in the ListTools handler, defining its name, description, and detailed input schema matching KlineParams.

  {
    name: "get_klines",
    description: "Get historical candlestick data",
    inputSchema: {
      type: "object",
      properties: {
        symbol: { 
          type: "string", 
          description: "Trading pair symbol (e.g., BTCUSDT)" 
        },
        type: { 
          type: "string", 
          enum: ["spot", "futures"], 
          description: "Market type" 
        },
        interval: {
          type: "string",
          enum: ["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w", "1M"],
          description: "Kline/candlestick chart interval"
        },
        limit: {
          type: "number",
          description: "Number of klines to retrieve (default 500, max 1000)"
        }
      },
      required: ["symbol", "type", "interval"]
    }
  },

• src/index.ts:237-249 (handler)

  MCP CallToolRequest handler for get_klines. Validates input using isKlineParams type guard, extracts parameters, calls the BinanceRestConnector.getKlines implementation, and formats response as JSON text.

  case "get_klines": {
    if (!isKlineParams(request.params.arguments)) {
      throw new Error('Invalid kline parameters');
    }
    const { symbol, type, interval, limit } = request.params.arguments;
    const data = await restConnector.getKlines(symbol, type, interval, limit);
    return {
      content: [{
        type: "text",
        text: JSON.stringify(data, null, 2)
      }]
    };
  }

• src/types/api-types.ts:6-11 (schema)

  TypeScript interface defining the input parameters for the get_klines tool, used for validation.

  export interface KlineParams {
    symbol: string;
    type: 'spot' | 'futures';
    interval: string;
    limit?: number;
  }

• src/types/api-types.ts:39-47 (schema)

  Type guard function for validating get_klines input parameters against KlineParams interface.

  export function isKlineParams(params: any): params is KlineParams {
    return (
      typeof params === 'object' &&
      typeof params.symbol === 'string' &&
      (params.type === 'spot' || params.type === 'futures') &&
      typeof params.interval === 'string' &&
      (params.limit === undefined || typeof params.limit === 'number')
    );
  }