get_positions
Retrieve current trading positions for a specified account ID on Interactive Brokers. Automates position tracking with OAuth authentication and pre-configured IB Gateway integration.
Instructions
Get current positions for an account
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| accountId | No | Account ID (optional, uses default if not provided) |
Implementation Reference
- src/tool-handlers.ts:332-371 (handler)The main handler function for the get_positions tool. Validates input, ensures gateway readiness and authentication, calls the IB client to fetch positions, and formats the response as MCP ToolHandlerResult.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/tools.ts:58-63 (registration)Registration of the get_positions tool with the MCP server, including name, description, input schema, and handler reference.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 (accountId: string), used in tool registration and type inference.export const GetPositionsZodShape = { accountId: z.string() };
- src/ib-client.ts:302-323 (helper)Underlying IBClient method that fetches positions via API GET request to /portfolio/positions or /portfolio/{accountId}/positions, called by the tool handler.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"); } }