Interactive Brokers MCP Server

Instructions

Implementation Reference

• src/tool-handlers.ts:373-402 (handler)

  The main tool handler function that ensures prerequisites and delegates to IBClient.getMarketData, then formats the response as MCP ToolHandlerResult.

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

• src/tool-definitions.ts:24-27 (schema)

  Zod shape definition for get_market_data input validation used in tool registration.

  export const GetMarketDataZodShape = {
    symbol: z.string(),
    exchange: z.string().optional()
  };

• src/tools.ts:66-71 (registration)

  MCP tool registration calling server.tool with name, description, schema, and handler.

  server.tool(
    "get_market_data",
    "Get real-time market data. Usage: `{ \"symbol\": \"AAPL\" }` or `{ \"symbol\": \"AAPL\", \"exchange\": \"NASDAQ\" }`.",
    GetMarketDataZodShape,
    async (args) => await handlers.getMarketData(args)
  );

• src/ib-client.ts:325-364 (helper)

  Core implementation that resolves symbol to contract ID and fetches market data snapshot from IB Gateway API.

  async getMarketData(symbol: string, exchange?: string): Promise<any> {
    try {
      // First, get the contract ID for the symbol
      const searchResponse = await this.client.get(
        `/iserver/secdef/search?symbol=${symbol}`
      );
      
      if (!searchResponse.data || searchResponse.data.length === 0) {
        throw new Error(`Symbol ${symbol} not found`);
      }
  
      const contract = searchResponse.data[0];
      const conid = contract.conid;
  
      // Get market data snapshot
      // Using corrected field IDs based on IB Client Portal API documentation:
      // 31=Last Price, 70=Day High, 71=Day Low, 82=Change, 83=Change%, 
      // 84=Bid, 85=Ask Size, 86=Ask, 87=Volume, 88=Bid Size
      const response = await this.client.get(
        `/iserver/marketdata/snapshot?conids=${conid}&fields=31,70,71,82,83,84,85,86,87,88`
      );
  
      return {
        symbol: symbol,
        contract: contract,
        marketData: response.data
      };
    } catch (error) {
      Logger.error("Failed to get market data:", error);
      
      // Check if this is likely an authentication error
      if (this.isAuthenticationError(error)) {
        const authError = new Error(`Authentication required to retrieve market data for ${symbol}. Please authenticate with Interactive Brokers first.`);
        (authError as any).isAuthError = true;
        throw authError;
      }
      
      throw new Error(`Failed to retrieve market data for ${symbol}`);
    }
  }