Interactive Brokers MCP Server

Instructions

Implementation Reference

• src/tool-handlers.ts:600-628 (handler)

  The primary handler function for the 'activate_alert' tool. It ensures the IB Gateway is ready and authenticated if needed, calls the IB client to perform the activation, and returns the result as JSON or formats any errors.

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

• src/tools.ts:126-131 (registration)

  Registers the 'activate_alert' tool with the MCP server, providing the name, description, input schema, and handler reference.

  // Register activate_alert tool
  server.tool(
    "activate_alert",
    "Activate a previously created alert. Usage: `{ \"accountId\": \"<id>\", \"alertId\": \"<alertId>\" }`.",
    ActivateAlertZodShape,
    async (args) => await handlers.activateAlert(args)

• src/tool-definitions.ts:86-89 (schema)

  Defines the Zod shape for the 'activate_alert' tool input validation, specifying accountId and alertId as required strings. Referenced in registration and used to derive the full schema and TypeScript type.

  export const ActivateAlertZodShape = {
    accountId: z.string(),
    alertId: z.string()
  };

• src/ib-client.ts:601-624 (helper)

  The IB client method that makes the actual HTTP POST request to Interactive Brokers' API endpoint to activate the specified alert for the account.

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