Interactive Brokers MCP Server

Instructions

Implementation Reference

• src/tool-handlers.ts:301-330 (handler)

  The main MCP tool handler for get_account_info. Ensures gateway readiness and authentication, calls IBClient.getAccountInfo(), formats response as ToolHandlerResult.

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

• src/tools.ts:49-55 (registration)

  MCP server tool registration for 'get_account_info', providing description, input schema, and handler reference.

  // Register get_account_info tool
  server.tool(
    "get_account_info",
    "Get account information and balances. Usage: `{ \"confirm\": true }`.",
    GetAccountInfoZodShape,
    async (args) => await handlers.getAccountInfo(args)
  );

• src/tool-definitions.ts:16-18 (schema)

  Zod shape used for input validation of get_account_info tool (requires 'confirm: true'). Full schema and TypeScript type also defined nearby.

  export const GetAccountInfoZodShape = {
    confirm: z.literal(true)
  };

• src/ib-client.ts:256-300 (helper)

  IBClient helper method implementing the core logic: fetches all portfolio accounts and their summary details via IB Gateway API endpoints.

  async getAccountInfo(): Promise<any> {
    Logger.log("[ACCOUNT-INFO] Starting getAccountInfo request...");
    try {
      Logger.log("[ACCOUNT-INFO] Fetching portfolio accounts...");
      const accountsResponse = await this.client.get("/portfolio/accounts");
      const accounts = accountsResponse.data;
      Logger.log(`[ACCOUNT-INFO] Found ${accounts?.length || 0} accounts:`, accounts);
  
      const result = {
        accounts: accounts,
        summaries: [] as any[]
      };
  
      Logger.log("[ACCOUNT-INFO] Processing account summaries...");
      for (let i = 0; i < accounts.length; i++) {
        const account = accounts[i];
        Logger.log(`[ACCOUNT-INFO] Processing account ${i + 1}/${accounts.length}: ${account.id}`);
        
        const summaryResponse = await this.client.get(
          `/portfolio/${account.id}/summary`
        );
        const summary = summaryResponse.data;
        Logger.log(`[ACCOUNT-INFO] Account ${account.id} summary:`, summary);
  
        result.summaries.push({
          accountId: account.id,
          summary: summary
        });
      }
  
      Logger.log(`[ACCOUNT-INFO] Completed processing ${result.summaries.length} accounts`);
      return result;
    } catch (error) {
      Logger.error("[ACCOUNT-INFO] Failed to get account info:", error);
      
      // Check if this is likely an authentication error
      if (this.isAuthenticationError(error)) {
        const authError = new Error("Authentication required to retrieve account information. Please authenticate with Interactive Brokers first.");
        (authError as any).isAuthError = true;
        throw authError;
      }
      
      throw new Error("Failed to retrieve account information");
    }
  }