Alpaca Trading MCP Server

Instructions

Implementation Reference

• src/server.py:547-614 (handler)

  The primary handler function for the 'get_portfolio_summary' tool. Decorated with @mcp.tool() which handles registration in FastMCP. Fetches account and positions data via helpers from calls.py and generates a formatted portfolio summary string.

  @mcp.tool()
  def get_portfolio_summary() -> str:
      """
      Get a comprehensive summary of the portfolio including account details and open positions.
      
      Returns:
          Portfolio summary with account and positions information
      """
      try:
          # Get account info
          account = calls.get_account(trading_client)
          
          # Get all positions
          positions = calls.get_positions(trading_client)
          
          # Generate summary
          summary = (
              f"Portfolio Summary\n"
              f"=================\n\n"
              f"Account Information:\n"
              f"-------------------\n"
              f"Status: {account.status}\n"
              f"Cash: ${account.cash:.2f}\n"
              f"Portfolio Value: ${account.portfolio_value:.2f}\n"
              f"Buying Power: ${account.buying_power:.2f}\n"
              f"Equity: ${account.equity:.2f}\n"
              f"Daytrade Count: {account.daytrade_count}\n"
              f"Pattern Day Trader: {account.pattern_day_trader}\n\n"
          )
          
          if positions:
              summary += f"Open Positions ({len(positions)}):\n-------------------\n"
              
              # Calculate total P/L and allocation
              total_pl = sum(pos.unrealized_pl for pos in positions)
              total_value = account.portfolio_value - account.cash
              
              for pos in positions:
                  pl_percent = pos.unrealized_plpc * 100
                  pl_sign = "+" if pos.unrealized_pl >= 0 else ""
                  allocation = (pos.market_value / account.portfolio_value) * 100 if account.portfolio_value > 0 else 0
                  
                  summary += (
                      f"{pos.symbol} ({pos.side.value.upper()}):\n"
                      f"  Quantity: {pos.qty}\n"
                      f"  Avg Entry: ${pos.avg_entry_price:.2f}\n"
                      f"  Current: ${pos.current_price:.2f}\n"
                      f"  Value: ${pos.market_value:.2f} ({allocation:.2f}% of portfolio)\n"
                      f"  P/L: {pl_sign}${pos.unrealized_pl:.2f} ({pl_sign}{pl_percent:.2f}%)\n\n"
                  )
              
              # Add overall P/L summary
              overall_pl_percent = (total_pl / total_value) * 100 if total_value > 0 else 0
              pl_sign = "+" if total_pl >= 0 else ""
              
              summary += (
                  f"Overall Position Summary:\n"
                  f"------------------------\n"
                  f"Total Position Value: ${total_value:.2f}\n"
                  f"Total Unrealized P/L: {pl_sign}${total_pl:.2f} ({pl_sign}{overall_pl_percent:.2f}%)\n"
                  f"Cash Allocation: ${account.cash:.2f} ({(account.cash / account.portfolio_value) * 100:.2f}% of portfolio)\n"
              )
          else:
              summary += "No open positions."
          
          return summary
      except Exception as e:
          return f"Error generating portfolio summary: {str(e)}"

• src/server.py:547-547 (registration)

  The @mcp.tool() decorator registers this function as an MCP tool named 'get_portfolio_summary'.

  @mcp.tool()