MCP Paradex Server

Instructions

Implementation Reference

• src/mcp_paradex/tools/account.py:50-82 (handler)

  The handler function decorated with @server.tool that implements the core logic of fetching and formatting account positions from the Paradex client.
  @server.tool(name="paradex_account_positions") async def get_account_positions(ctx: Context) -> dict: """ Analyze your open positions to monitor exposure, profitability, and risk. Use this tool when you need to: - Check the status and P&L of all your open positions - Monitor your liquidation prices and margin requirements - Assess your exposure across different markets - Make decisions about position management (scaling, hedging, closing) Understanding your current positions is fundamental to proper risk management and is the starting point for many trading decisions. Example use cases: - Checking the unrealized P&L of your positions - Monitoring liquidation prices during market volatility - Assessing total exposure across related assets - Verifying entry prices and position sizes """ client = await get_authenticated_paradex_client() response = client.fetch_positions() if "error" in response: await ctx.error(response) raise Exception(response["error"]) positions = position_adapter.validate_python(response["results"]) results = { "description": Position.__doc__.strip() if Position.__doc__ else None, "fields": Position.model_json_schema(), "results": positions, } return results
• src/mcp_paradex/models.py:52-107 (schema)

  Pydantic BaseModel defining the schema for Position data used in the tool's response validation and formatting.
  class Position(BaseModel): """Position model representing a trading position on Paradex.""" id: Annotated[str, Field(description="Unique string ID for the position")] account: Annotated[str, Field(description="Account ID of the position")] market: Annotated[str, Field(description="Market for position")] status: Annotated[ str, Field(description="Status of Position : Open or Closed", enum=["OPEN", "CLOSED"]) ] side: Annotated[str, Field(description="Position Side : Long or Short", enum=["SHORT", "LONG"])] size: Annotated[ float, Field(description="Size of the position with sign (positive if long or negative if short)"), ] average_entry_price: Annotated[float, Field(description="Average entry price")] average_entry_price_usd: Annotated[float, Field(description="Average entry price in USD")] average_exit_price: Annotated[float, Field(description="Average exit price")] unrealized_pnl: Annotated[ float, Field(description="Unrealized P&L of the position in the quote asset") ] unrealized_funding_pnl: Annotated[ float, Field(description="Unrealized running funding P&L for the position") ] cost: Annotated[float, Field(description="Position cost")] cost_usd: Annotated[float, Field(description="Position cost in USD")] cached_funding_index: Annotated[float, Field(description="Position cached funding index")] last_updated_at: Annotated[int, Field(description="Position last update time")] last_fill_id: Annotated[ str, Field(description="Last fill ID to which the position is referring") ] seq_no: Annotated[ int, Field( description="Unique increasing number (non-sequential) that is assigned to this position update. Can be used to deduplicate multiple feeds" ), ] liquidation_price: Annotated[ str, Field(default="", description="Liquidation price of the position") ] leverage: Annotated[float, Field(default=0, description="Leverage of the position")] realized_positional_pnl: Annotated[ float, Field( default=0, description="Realized PnL including both positional PnL and funding payments. Reset to 0 when position is closed or flipped.", ), ] created_at: Annotated[int, Field(default=0, description="Position creation time")] closed_at: Annotated[int, Field(default=0, description="Position closed time")] realized_positional_funding_pnl: Annotated[ str, Field( default="", description="Realized Funding PnL for the position. Reset to 0 when position is closed or flipped.", ), ]
• src/mcp_paradex/tools/account.py:50-50 (registration)

  The @server.tool decorator registers the get_account_positions function as the MCP tool named 'paradex_account_positions'.
  @server.tool(name="paradex_account_positions")