Interactive Brokers MCP Server

Instructions

Implementation Reference

• src/tool-handlers.ts:444-473 (handler)

  Main tool handler for get_order_status: ensures gateway and auth ready, calls ibClient.getOrderStatus, returns formatted ToolHandlerResult with JSON stringified response or error.

  async getOrderStatus(input: GetOrderStatusInput): Promise<ToolHandlerResult> {
    try {
      // Ensure Gateway is ready
      await this.ensureGatewayReady();
      
      // Ensure authentication in headless mode
      if (this.context.config.IB_HEADLESS_MODE) {
        await this.ensureAuth();
      }
      
      const result = await this.context.ibClient.getOrderStatus(input.orderId);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: this.formatError(error),
          },
        ],
      };
    }
  }

• src/tools.ts:86-91 (registration)

  Registers the 'get_order_status' MCP tool with server.tool, providing name, description, Zod input shape, and delegating handler.

  server.tool(
    "get_order_status",
    "Get the status of a specific order. Usage: `{ \"orderId\": \"12345\" }`.",
    GetOrderStatusZodShape,
    async (args) => await handlers.getOrderStatus(args)
  );

• src/tool-definitions.ts:40-42 (schema)

  Zod input shape for get_order_status tool: requires 'orderId' string. Used in registration and type inference.

  export const GetOrderStatusZodShape = {
    orderId: z.string()
  };

• src/ib-client.ts:492-508 (helper)

  Low-level IB API client method that fetches order status via GET /iserver/account/orders/{orderId}, handles auth errors, called by tool handler.

  async getOrderStatus(orderId: string): Promise<any> {
    try {
      const response = await this.client.get(`/iserver/account/orders/${orderId}`);
      return response.data;
    } catch (error) {
      Logger.error("Failed to get order status:", error);
      
      // Check if this is likely an authentication error
      if (this.isAuthenticationError(error)) {
        const authError = new Error(`Authentication required to get order status for order ${orderId}. Please authenticate with Interactive Brokers first.`);
        (authError as any).isAuthError = true;
        throw authError;
      }
      
      throw new Error(`Failed to get status for order ${orderId}`);
    }
  }