Interactive Brokers MCP Server

Instructions

Implementation Reference

• src/tool-handlers.ts:538-566 (handler)

  Main tool handler for 'get_alerts': ensures prerequisites (gateway/auth), calls IBClient.getAlerts, returns formatted result or error.

  async getAlerts(input: GetAlertsInput): 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.getAlerts(input.accountId);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: this.formatError(error),
          },
        ],
      };
    }

• src/tools.ts:110-116 (registration)

  MCP server.tool registration for 'get_alerts' tool with description, Zod shape, and handler reference.

  // Register get_alerts tool
  server.tool(
    "get_alerts",
    "Get all trading alerts for an account. Usage: `{ \"accountId\": \"<id>\" }`.",
    GetAlertsZodShape,
    async (args) => await handlers.getAlerts(args)
  );

• src/tool-definitions.ts:53-55 (schema)

  Zod input shape for get_alerts: requires 'accountId' string. Used for validation in registration.

  export const GetAlertsZodShape = {
    accountId: z.string()
  };

• src/ib-client.ts:540-561 (helper)

  IBClient helper method implementing the core API call to retrieve alerts via IB Gateway REST API.

  async getAlerts(accountId: string): Promise<any> {
    try {
      Logger.log(`[ALERT] Getting alerts for account ${accountId}`);
      
      const response = await this.client.get(
        `/iserver/account/${accountId}/alerts`
      );
  
      Logger.log("[ALERT] Get alerts response:", response.data);
      return response.data;
    } catch (error) {
      Logger.error("[ALERT] Failed to get alerts:", error);
      
      // Check if this is likely an authentication error
      if (this.isAuthenticationError(error)) {
        const authError = new Error("Authentication required to get alerts. Please authenticate with Interactive Brokers first.");
        (authError as any).isAuthError = true;
        throw authError;
      }
      
      throw new Error("Failed to get alerts: " + (error as any).message);
    }