get_positions
Retrieve current trading positions from Interactive Brokers accounts to monitor portfolio holdings and track investment exposure.
Instructions
Get current positions. Usage: {} or { "accountId": "<id>" }.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| accountId | Yes |
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"); } }