Interactive Brokers MCP Server

Instructions

Implementation Reference

• src/tools.ts:57-63 (registration)

  Registration of the 'get_positions' MCP tool using server.tool(). It specifies the name, description, input schema (GetPositionsZodShape), and handler function.

  // Register get_positions tool
  server.tool(
    "get_positions", 
    "Get current positions. Usage: `{}` or `{ \"accountId\": \"<id>\" }`.",
    GetPositionsZodShape,
    async (args) => await handlers.getPositions(args)
  );

• src/tool-definitions.ts:20-22 (schema)

  Zod shape definition for 'get_positions' input validation, requiring an 'accountId' string.

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

• src/tool-handlers.ts:332-371 (handler)

  Primary handler function in ToolHandlers class that executes the get_positions tool logic. Validates input, ensures gateway and auth readiness, calls IBClient.getPositions, formats result as MCP response.

  async getPositions(input: GetPositionsInput): Promise<ToolHandlerResult> {
    try {
      if (!input.accountId) {
        return {
          content: [
            {
              type: "text",
              text: "Account ID is required",
            },
          ],
        };
      }
      // 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.getPositions(input.accountId);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: this.formatError(error),
          },
        ],
      };
    }
  }

• src/ib-client.ts:302-323 (helper)

  IBClient helper method that makes the actual API call to IB Gateway's /portfolio/{accountId}/positions endpoint to retrieve positions data.

  async getPositions(accountId?: string): Promise<any> {
    try {
      let url = "/portfolio/positions";
      if (accountId) {
        url = `/portfolio/${accountId}/positions`;
      }
  
      const response = await this.client.get(url);
      return response.data;
    } catch (error) {
        Logger.error("Failed to get positions:", error);
      
      // Check if this is likely an authentication error
      if (this.isAuthenticationError(error)) {
        const authError = new Error("Authentication required to retrieve positions. Please authenticate with Interactive Brokers first.");
        (authError as any).isAuthError = true;
        throw authError;
      }
      
      throw new Error("Failed to retrieve positions");
    }
  }