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'