Alpaca Trading MCP Server

Instructions

Implementation Reference

• src/server.py:439-502 (handler)

  The primary handler function for the 'place_stop_limit_order' tool. It performs input validation using enums, constructs an AlpacaOrderRequest, calls the helper place_order, and formats the response.
  @mcp.tool() def place_stop_limit_order( symbol: str, quantity: float, side: str, stop_price: float, limit_price: float, time_in_force: str = "day" ) -> str: """ Place a stop-limit order combining stop and limit order features. Args: symbol: Stock symbol (e.g., 'AAPL') quantity: Number of shares to buy or sell (can be fractional) side: Either 'buy' or 'sell' stop_price: Price that triggers the order limit_price: Maximum/minimum price for the triggered order time_in_force: Order duration - 'day', 'gtc' (good till canceled) Returns: Order confirmation details """ # Validate side try: order_side = AlpacaOrderSide(side.lower()) except ValueError: return f"Invalid side: {side}. Must be 'buy' or 'sell'." # Validate time in force try: order_tif = AlpacaTimeInForce(time_in_force.lower()) except ValueError: return f"Invalid time in force: {time_in_force}. Valid options are: day, gtc" # Create order request order_request = AlpacaOrderRequest( symbol=symbol, qty=float(quantity), side=order_side, type=AlpacaOrderType.STOP_LIMIT, time_in_force=order_tif, stop_price=float(stop_price), limit_price=float(limit_price) ) try: order = calls.place_order(trading_client, order_request) return ( f"Stop-limit order placed successfully!\n\n" f"Order ID: {order.id}\n" f"Symbol: {order.symbol}\n" f"Side: {order.side.value}\n" f"Type: {order.type.value}\n" f"Quantity: {order.qty}\n" f"Stop Price: ${order.stop_price:.2f}\n" f"Limit Price: ${order.limit_price:.2f}\n" f"Time in Force: {order.time_in_force.value}\n" f"Status: {order.status.value}\n" f"Created At: {order.created_at}\n" ) except Exception as e: return f"Error placing stop-limit order: {str(e)}"
• src/models.py:87-97 (schema)

  Pydantic model providing input schema and validation for order requests, supporting stop_limit orders with required stop_price and limit_price fields.
  class AlpacaOrderRequest(BaseModel): symbol: str qty: Union[int, float] side: AlpacaOrderSide type: AlpacaOrderType time_in_force: AlpacaTimeInForce limit_price: Optional[float] = None stop_price: Optional[float] = None client_order_id: Optional[str] = None extended_hours: Optional[bool] = False
• src/server.py:439-439 (registration)

  The @mcp.tool() decorator registers the place_stop_limit_order function as an MCP tool in the FastMCP server.
  @mcp.tool()
• src/calls.py:44-97 (helper)

  Core helper function that translates the validated AlpacaOrderRequest into Alpaca SDK StopLimitOrderRequest and submits it to the trading API.
  def place_order(client: TradingClient, order_details: AlpacaOrderRequest): """ Place an order with flexible order types :param client: Alpaca trading client :param order_details: Order request details :return: Placed AlpacaOrder """ # Map Pydantic model to Alpaca order request based on order type if order_details.type == AlpacaOrderType.MARKET: order_request = MarketOrderRequest( symbol=order_details.symbol, qty=order_details.qty, side=order_details.side, time_in_force=order_details.time_in_force ) elif order_details.type == AlpacaOrderType.LIMIT: if not order_details.limit_price: raise ValueError("Limit price is required for limit orders") order_request = LimitOrderRequest( symbol=order_details.symbol, qty=order_details.qty, side=order_details.side, time_in_force=order_details.time_in_force, limit_price=order_details.limit_price ) elif order_details.type == AlpacaOrderType.STOP: if not order_details.stop_price: raise ValueError("Stop price is required for stop orders") order_request = StopOrderRequest( symbol=order_details.symbol, qty=order_details.qty, side=order_details.side, time_in_force=order_details.time_in_force, stop_price=order_details.stop_price ) elif order_details.type == AlpacaOrderType.STOP_LIMIT: if not (order_details.stop_price and order_details.limit_price): raise ValueError("Both stop and limit prices are required for stop-limit orders") order_request = StopLimitOrderRequest( symbol=order_details.symbol, qty=order_details.qty, side=order_details.side, time_in_force=order_details.time_in_force, stop_price=order_details.stop_price, limit_price=order_details.limit_price ) else: raise ValueError(f"Unsupported order type: {order_details.type}") # Submit order order = client.submit_order(order_request) return AlpacaOrder(**order.__dict__)
• src/models.py:21-42 (schema)

  Enum definitions for order side, type (including STOP_LIMIT), and time_in_force used for input validation in the tool handler.
  class AlpacaOrderSide(str, Enum): BUY = 'buy' SELL = 'sell' class AlpacaOrderType(str, Enum): MARKET = 'market' LIMIT = 'limit' STOP = 'stop' STOP_LIMIT = 'stop_limit' TRAILING_STOP = 'trailing_stop' class AlpacaPositionSide(str, Enum): LONG = 'long' SHORT = 'short' class AlpacaTimeInForce(str, Enum): DAY = 'day' GTC = 'gtc' OPG = 'opg' CLS = 'cls' IOC = 'ioc' FOK = 'fok'