Bybit MCP Server

Instructions

Implementation Reference

• src/tools/GetTrades.ts:41-95 (handler)

  Executes the get_trades tool: validates symbol (required), optional category (spot/linear/inverse) and limit, fetches recent public trades from Bybit API using getPublicTradingHistory, formats response with id, symbol, price, size, side, time, isBlockTrade, handles errors via BaseTool.

  async toolCall(request: z.infer<typeof CallToolRequestSchema>) {
    try {
      const args = request.params.arguments as unknown
      if (!args || typeof args !== 'object') {
        throw new Error("Invalid arguments")
      }
  
      const typedArgs = args as Record<string, unknown>
  
      if (!typedArgs.symbol || typeof typedArgs.symbol !== 'string') {
        throw new Error("Missing or invalid symbol parameter")
      }
  
      const symbol = typedArgs.symbol
      const category = (
        typedArgs.category &&
        typeof typedArgs.category === 'string' &&
        ["spot", "linear", "inverse"].includes(typedArgs.category)
      ) ? typedArgs.category as SupportedCategory
        : CONSTANTS.DEFAULT_CATEGORY as SupportedCategory
  
      const limit = (
        typedArgs.limit &&
        typeof typedArgs.limit === 'string' &&
        ["1", "10", "50", "100", "200", "500", "1000"].includes(typedArgs.limit)
      ) ? parseInt(typedArgs.limit, 10) : 200
  
      const params: GetPublicTradingHistoryParamsV5 = {
        category,
        symbol,
        limit,
      }
  
      const response = await this.client.getPublicTradingHistory(params)
  
      if (response.retCode !== 0) {
        throw new Error(`Bybit API error: ${response.retMsg}`)
      }
  
      // Transform the trade data into a more readable format and return as array
      const formattedTrades = response.result.list.map(trade => ({
        id: trade.execId,
        symbol: trade.symbol,
        price: trade.price,
        size: trade.size,
        side: trade.side,
        time: trade.time,
        isBlockTrade: trade.isBlockTrade,
      }))
  
      return this.formatResponse(formattedTrades)
    } catch (error) {
      return this.handleError(error)
    }
  }

• src/tools/GetTrades.ts:16-39 (schema)

  Tool definition including name, description, and input schema validation for parameters: symbol (required string), category (enum string), limit (enum string).

  toolDefinition: Tool = {
    name: this.name,
    description: "Get recent trades for a trading pair",
    inputSchema: {
      type: "object",
      properties: {
        symbol: {
          type: "string",
          description: "Trading pair symbol (e.g., 'BTCUSDT')",
        },
        category: {
          type: "string",
          description: "Category of the instrument (spot, linear, inverse)",
          enum: ["spot", "linear", "inverse"],
        },
        limit: {
          type: "string",
          description: "Limit for the number of trades (max 1000)",
          enum: ["1", "10", "50", "100", "200", "500", "1000"],
        },
      },
      required: ["symbol"],
    },
  };

• src/utils/toolLoader.ts:23-81 (registration)

  Dynamically discovers, imports, instantiates (new ToolClass()), validates, and collects all BaseToolImplementation subclasses from src/tools/*.ts including GetTrades, returning array of tool instances.

  export async function loadTools(): Promise<BaseToolImplementation[]> {
    try {
      const toolsPath = await findToolsPath()
      const files = await fs.readdir(toolsPath)
      const tools: BaseToolImplementation[] = []
  
      for (const file of files) {
        if (!isToolFile(file)) {
          continue
        }
  
        try {
          const modulePath = `file://${join(toolsPath, file)}`
          const { default: ToolClass } = await import(modulePath)
  
          if (!ToolClass || typeof ToolClass !== 'function') {
            console.warn(JSON.stringify({
              type: "warning",
              message: `Invalid tool class in ${file}`
            }))
            continue
          }
  
          const tool = new ToolClass()
  
          if (
            tool instanceof BaseToolImplementation &&
            tool.name &&
            tool.toolDefinition &&
            typeof tool.toolCall === "function"
          ) {
            tools.push(tool)
            console.info(JSON.stringify({
              type: "info",
              message: `Loaded tool: ${tool.name}`
            }))
          } else {
            console.warn(JSON.stringify({
              type: "warning",
              message: `Invalid tool implementation in ${file}`
            }))
          }
        } catch (error) {
          console.error(JSON.stringify({
            type: "error",
            message: `Error loading tool from ${file}: ${error instanceof Error ? error.message : String(error)}`
          }))
        }
      }
  
      return tools
    } catch (error) {
      console.error(JSON.stringify({
        type: "error",
        message: `Failed to load tools: ${error instanceof Error ? error.message : String(error)}`
      }))
      return []
    }
  }

• src/index.ts:82-115 (registration)

  Registers the generic MCP CallTool handler: looks up tool by name from toolsMap (populated with get_trades), validates arguments, calls tool.toolCall(request).

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    try {
      if (!toolsMap) {
        throw new Error("Tools not initialized")
      }
  
      const tool = toolsMap.get(request.params.name)
      if (!tool) {
        throw {
          code: METHOD_NOT_FOUND,
          message: `Unknown tool: ${request.params.name}. Available tools: ${Array.from(
            toolsMap.keys()
          ).join(", ")}`
        }
      }
  
      if (!request.params.arguments || typeof request.params.arguments !== 'object') {
        throw {
          code: INVALID_PARAMS,
          message: "Invalid or missing arguments"
        }
      }
  
      return tool.toolCall(request)
    } catch (error: any) {
      if (error.code) {
        throw error
      }
      throw {
        code: INTERNAL_ERROR,
        message: error instanceof Error ? error.message : String(error)
      }
    }
  })

• src/index.ts:73-80 (registration)

  Registers MCP ListTools handler: returns array of tool definitions (including get_trades schema) from loaded toolsMap.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    if (!toolsMap || toolsMap.size === 0) {
      return { tools: [] }
    }
    return {
      tools: Array.from(toolsMap.values()).map((tool) => tool.toolDefinition),
    }
  })