Alpaca Trading MCP Server

Instructions

Implementation Reference

• src/server.py:377-437 (handler)

  The primary handler function for the 'place_stop_order' MCP tool. It validates input parameters using enums, constructs an AlpacaOrderRequest with STOP order type, submits the order through the calls.place_order helper, and returns a formatted confirmation string.
  @mcp.tool() def place_stop_order( symbol: str, quantity: float, side: str, stop_price: float, time_in_force: str = "day" ) -> str: """ Place a stop order to buy or sell a stock when it reaches a specified price. 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 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, time_in_force=order_tif, stop_price=float(stop_price) ) try: order = calls.place_order(trading_client, order_request) return ( f"Stop 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"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 order: {str(e)}"
• src/models.py:87-97 (schema)

  Pydantic BaseModel defining the input schema and validation for all order requests, including the stop_price field required for STOP orders used by place_stop_order.
  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/calls.py:44-96 (helper)

  Helper function that maps the AlpacaOrderRequest to the appropriate Alpaca SDK order request (StopOrderRequest for STOP type) and submits it to the trading client, returning the resulting order object.
  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:25-31 (schema)

  Enum defining order types, including STOP used in the place_stop_order tool for order type specification and validation.
  class AlpacaOrderType(str, Enum): MARKET = 'market' LIMIT = 'limit' STOP = 'stop' STOP_LIMIT = 'stop_limit' TRAILING_STOP = 'trailing_stop'
• src/models.py:21-43 (schema)

  Enums for order side (buy/sell) and time_in_force used for input validation in the place_stop_order 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'