Interactive Brokers MCP Server

Instructions

Implementation Reference

• src/tool-handlers.ts:569-597 (handler)

  The primary handler function for the 'create_alert' MCP tool. Ensures gateway readiness and authentication (if headless mode), calls IBClient.createAlert, formats the result as ToolHandlerResult, and handles errors.

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

• src/tool-definitions.ts:57-84 (schema)

  Zod input schema shape (CreateAlertZodShape) defining validation rules for the create_alert tool parameters, including accountId and detailed alertRequest structure.

  export const CreateAlertZodShape = {
    accountId: z.string(),
    alertRequest: z.object({
      orderId: z.number().optional(),
      alertName: z.string(),
      alertMessage: z.string().optional(),
      alertRepeatable: z.number().optional(),
      expireTime: z.string().optional(),
      outsideRth: z.number().optional(),
      iTWSOrdersOnly: z.number().optional(),
      showPopup: z.number().optional(),
      toolId: z.number().optional(),
      playAudio: z.string().optional(),
      emailNotification: z.string().optional(),
      sendMessage: z.number().optional(),
      tif: z.string().optional(),
      logicBind: z.string().optional(),
      conditions: z.array(z.object({
        conidex: z.string(),
        type: z.string(),
        operator: z.string(),
        triggerMethod: z.string(),
        value: z.string(),
        logicBind: z.string().optional(),
        timeZone: z.string().optional()
      }))
    })
  };

• src/tools.ts:118-123 (registration)

  MCP server tool registration for 'create_alert', specifying name, description, input schema, and handler function reference.

  // Register create_alert tool
  server.tool(
    "create_alert",
    "Create a new trading alert. Usage: `{ \"accountId\": \"<id>\", \"alertRequest\": { \"alertName\": \"Price Alert\", \"conditions\": [{ \"conidex\": \"265598\", \"type\": \"price\", \"operator\": \">\", \"triggerMethod\": \"last\", \"value\": \"150\" }] } }`.",
    CreateAlertZodShape,
    async (args) => await handlers.createAlert(args)

• src/ib-client.ts:570-592 (helper)

  IBClient helper method that performs the actual HTTP POST request to the IB Gateway API endpoint /iserver/account/{accountId}/alert to create the alert, with logging and authentication error handling.

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