alpacahq/alpaca-mcp-server

get_account_info

Retrieves and formats the current account information including balances and status.

Returns:
    str: Formatted string containing account details including:
        - Account ID
        - Status
        - Currency
        - Buying Power
        - Cash Balance
        - Portfolio Value
        - Equity
        - Market Values
        - Pattern Day Trader Status
        - Day Trades Remaining

get_positions

Retrieves and formats all current positions in the portfolio.

Returns:
    str: Formatted string containing details of all open positions including:
        - Symbol
        - Quantity
        - Market Value
        - Average Entry Price
        - Current Price
        - Unrealized P/L

get_open_position

Retrieves and formats details for a specific open position.

Args:
    symbol (str): The symbol name of the asset to get position for (e.g., 'AAPL', 'MSFT')

Returns:
    str: Formatted string containing the position details or an error message

get_stock_quote

Retrieves and formats the latest quote for a stock.

Args:
    symbol (str): Stock ticker symbol (e.g., AAPL, MSFT)

Returns:
    str: Formatted string containing:
        - Ask Price
        - Bid Price
        - Ask Size
        - Bid Size
        - Timestamp

get_stock_bars

Retrieves and formats historical price bars for a stock with configurable timeframe and time range.

Args:
    symbol (str): Stock ticker symbol (e.g., AAPL, MSFT)
    days (int): Number of days to look back (default: 5, ignored if start/end provided)
    timeframe (str): Bar timeframe - supports flexible Alpaca formats:
        - Minutes: "1Min", "2Min", "3Min", "4Min", "5Min", "15Min", "30Min", etc.
        - Hours: "1Hour", "2Hour", "3Hour", "4Hour", "6Hour", etc.
        - Days: "1Day", "2Day", "3Day", etc.
        - Weeks: "1Week", "2Week", etc.
        - Months: "1Month", "2Month", etc.
        (default: "1Day")
    limit (Optional[int]): Maximum number of bars to return (optional)
    start (Optional[str]): Start time in ISO format (e.g., "2023-01-01T09:30:00" or "2023-01-01")
    end (Optional[str]): End time in ISO format (e.g., "2023-01-01T16:00:00" or "2023-01-01")

Returns:
    str: Formatted string containing historical price data with timestamps, OHLCV data

get_stock_trades

Retrieves and formats historical trades for a stock.

Args:
    symbol (str): Stock ticker symbol (e.g., 'AAPL', 'MSFT')
    days (int): Number of days to look back (default: 5)
    limit (Optional[int]): Upper limit of number of data points to return
    sort (Optional[Sort]): Chronological order of response (ASC or DESC)
    feed (Optional[DataFeed]): The stock data feed to retrieve from
    currency (Optional[SupportedCurrencies]): Currency for prices (default: USD)
    asof (Optional[str]): The asof date in YYYY-MM-DD format

Returns:
    str: Formatted string containing trade history or an error message

get_stock_latest_trade

Get the latest trade for a stock.

Args:
    symbol: Stock ticker symbol (e.g., 'AAPL', 'MSFT')
    feed: The stock data feed to retrieve from (optional)
    currency: The currency for prices (optional, defaults to USD)

Returns:
    A formatted string containing the latest trade details or an error message

get_stock_latest_bar

Get the latest minute bar for a stock.

Args:
    symbol: Stock ticker symbol (e.g., 'AAPL', 'MSFT')
    feed: The stock data feed to retrieve from (optional)
    currency: The currency for prices (optional, defaults to USD)

Returns:
    A formatted string containing the latest bar details or an error message

get_stock_snapshot

Retrieves comprehensive snapshots of stock symbols including latest trade, quote, minute bar, daily bar, and previous daily bar.

Args:
    symbol_or_symbols: Single stock symbol or list of stock symbols (e.g., 'AAPL' or ['AAPL', 'MSFT'])
    feed: The stock data feed to retrieve from (optional)
    currency: The currency the data should be returned in (default: USD)

Returns:
    Formatted string with comprehensive snapshots including:
    - latest_quote: Current bid/ask prices and sizes
    - latest_trade: Most recent trade price, size, and exchange
    - minute_bar: Latest minute OHLCV bar
    - daily_bar: Current day's OHLCV bar  
    - previous_daily_bar: Previous trading day's OHLCV bar

get_orders

Retrieves and formats orders with the specified status.

Args:
    status (str): Order status to filter by (open, closed, all)
    limit (int): Maximum number of orders to return (default: 10)

Returns:
    str: Formatted string containing order details including:
        - Symbol
        - ID
        - Type
        - Side
        - Quantity
        - Status
        - Submission Time
        - Fill Details (if applicable)

place_stock_order

Places an order of any supported type (MARKET, LIMIT, STOP, STOP_LIMIT, TRAILING_STOP) using the correct Alpaca request class.

Args:
    symbol (str): Stock ticker symbol (e.g., AAPL, MSFT)
    side (str): Order side (buy or sell)
    quantity (float): Number of shares to buy or sell
    order_type (str): Order type (MARKET, LIMIT, STOP, STOP_LIMIT, TRAILING_STOP). Default is MARKET.
    time_in_force (str): Time in force for the order. Valid options for equity trading: 
        DAY, GTC, OPG, CLS, IOC, FOK (default: DAY)
    limit_price (float): Limit price (required for LIMIT, STOP_LIMIT)
    stop_price (float): Stop price (required for STOP, STOP_LIMIT)
    trail_price (float): Trail price (for TRAILING_STOP)
    trail_percent (float): Trail percent (for TRAILING_STOP)
    extended_hours (bool): Allow execution during extended hours (default: False)
    client_order_id (str): Optional custom identifier for the order

Returns:
    str: Formatted string containing order details or error message.

cancel_all_orders

Cancel all open orders.

Returns:
    A formatted string containing the status of each cancelled order.

cancel_order_by_id

Cancel a specific order by its ID.

Args:
    order_id: The UUID of the order to cancel
    
Returns:
    A formatted string containing the status of the cancelled order.

close_position

Closes a specific position for a single symbol.

Args:
    symbol (str): The symbol of the position to close
    qty (Optional[str]): Optional number of shares to liquidate
    percentage (Optional[str]): Optional percentage of shares to liquidate (must result in at least 1 share)

Returns:
    str: Formatted string containing position closure details or error message

close_all_positions

Closes all open positions.

Args:
    cancel_orders (bool): If True, cancels all open orders before liquidating positions

Returns:
    str: Formatted string containing position closure results

get_asset_info

Retrieves and formats detailed information about a specific asset.

Args:
    symbol (str): The symbol of the asset to get information for

Returns:
    str: Formatted string containing asset details including:
        - Name
        - Exchange
        - Class
        - Status
        - Trading Properties

get_all_assets

Get all available assets with optional filtering.

Args:
    status: Filter by asset status (e.g., 'active', 'inactive')
    asset_class: Filter by asset class (e.g., 'us_equity', 'crypto')
    exchange: Filter by exchange (e.g., 'NYSE', 'NASDAQ')
    attributes: Comma-separated values to query for multiple attributes

create_watchlist

Creates a new watchlist with specified symbols.

Args:
    name (str): Name of the watchlist
    symbols (List[str]): List of symbols to include in the watchlist

Returns:
    str: Confirmation message with watchlist creation status

get_watchlists

Get all watchlists for the account.

update_watchlist

Update an existing watchlist.

get_market_clock

Retrieves and formats current market status and next open/close times.

Returns:
    str: Formatted string containing:
        - Current Time
        - Market Open Status
        - Next Open Time
        - Next Close Time

get_market_calendar

Retrieves and formats market calendar for specified date range.

Args:
    start_date (str): Start date in YYYY-MM-DD format
    end_date (str): End date in YYYY-MM-DD format

Returns:
    str: Formatted string containing market calendar information

get_corporate_announcements

Retrieves and formats corporate action announcements.

Args:
    ca_types (Optional[List[CorporateActionsType]]): List of corporate action types to filter by (default: all types)
        Available types from https://alpaca.markets/sdks/python/api_reference/data/enums.html#corporateactionstype:
        - CorporateActionsType.REVERSE_SPLIT: Reverse split
        - CorporateActionsType.FORWARD_SPLIT: Forward split  
        - CorporateActionsType.UNIT_SPLIT: Unit split
        - CorporateActionsType.CASH_DIVIDEND: Cash dividend
        - CorporateActionsType.STOCK_DIVIDEND: Stock dividend
        - CorporateActionsType.SPIN_OFF: Spin off
        - CorporateActionsType.CASH_MERGER: Cash merger
        - CorporateActionsType.STOCK_MERGER: Stock merger
        - CorporateActionsType.STOCK_AND_CASH_MERGER: Stock and cash merger
        - CorporateActionsType.REDEMPTION: Redemption
        - CorporateActionsType.NAME_CHANGE: Name change
        - CorporateActionsType.WORTHLESS_REMOVAL: Worthless removal
        - CorporateActionsType.RIGHTS_DISTRIBUTION: Rights distribution
    start (Optional[date]): Start date for the announcements (default: current day)
    end (Optional[date]): End date for the announcements (default: current day)
    symbols (Optional[List[str]]): Optional list of stock symbols to filter by
    cusips (Optional[List[str]]): Optional list of CUSIPs to filter by
    ids (Optional[List[str]]): Optional list of corporate action IDs (mutually exclusive with other filters)
    limit (Optional[int]): Maximum number of results to return (default: 1000)
    sort (Optional[str]): Sort order (asc or desc, default: asc)

Returns:
    str: Formatted string containing corporate announcement details
    
References:
    - API Documentation: https://docs.alpaca.markets/reference/corporateactions-1
    - CorporateActionsType Enum: https://alpaca.markets/sdks/python/api_reference/data/enums.html#corporateactionstype
    - CorporateActionsRequest: https://alpaca.markets/sdks/python/api_reference/data/corporate_actions/requests.html#corporateactionsrequest

get_option_contracts

Retrieves metadata for option contracts based on specified criteria. This endpoint returns contract specifications
and static data, not real-time pricing information.

Args:
    underlying_symbol (str): The symbol of the underlying asset (e.g., 'AAPL')
    expiration_date (Optional[date]): Optional specific expiration date for the options
    expiration_month (Optional[int]): Optional expiration month (1-12) to get all contracts for that month
    expiration_year (Optional[int]): Optional expiration year (required if expiration_month is provided)
    expiration_week_start (Optional[date]): Optional start date of week to find all contracts expiring in that week (Monday-Sunday)
    strike_price_gte (Optional[str]): Optional minimum strike price
    strike_price_lte (Optional[str]): Optional maximum strike price
    type (Optional[ContractType]): Optional contract type (CALL or PUT)
    status (Optional[AssetStatus]): Optional asset status filter (e.g., ACTIVE)
    root_symbol (Optional[str]): Optional root symbol for the option
    limit (Optional[int]): Optional maximum number of contracts to return

Returns:
    str: Formatted string containing option contract metadata including:
        - Contract ID and Symbol
        - Name and Type (Call/Put)
        - Strike Price and Expiration Date
        - Exercise Style (American/European)
        - Contract Size and Status
        - Open Interest and Close Price
        - Underlying Asset Information ('underlying_asset_id', 'underlying_symbol', 'underlying_name', 'underlying_exchange')
        - Trading Status (Tradable/Non-tradable)

Note:
    This endpoint returns contract specifications and static data. For real-time pricing
    information (bid/ask prices, sizes, etc.), use get_option_latest_quote instead.
    
    For month-based queries, use expiration_month and expiration_year instead of expiration_date.
    For week-based queries, use expiration_week_start to find all contracts expiring in that week.
    The function will check all dates from Monday through Sunday of that week.
    
    When more than 500 contracts are found, a guidance message is displayed instead of 
    overwhelming output to help users narrow their search criteria.

get_option_latest_quote

Retrieves and formats the latest quote for an option contract. This endpoint returns real-time
pricing and market data, including bid/ask prices, sizes, and exchange information.

Args:
    symbol (str): The option contract symbol (e.g., 'AAPL230616C00150000')
    feed (Optional[OptionsFeed]): The source feed of the data (opra or indicative).
        Default: opra if the user has the options subscription, indicative otherwise.

Returns:
    str: Formatted string containing the latest quote information including:
        - Ask Price and Ask Size
        - Bid Price and Bid Size
        - Ask Exchange and Bid Exchange
        - Trade Conditions
        - Tape Information
        - Timestamp (in UTC)

Note:
    This endpoint returns real-time market data. For contract specifications and static data,
    use get_option_contracts instead.

get_option_snapshot

Retrieves comprehensive snapshots of option contracts including latest trade, quote, implied volatility, and Greeks.
This endpoint provides a complete view of an option's current market state and theoretical values.

Args:
    symbol_or_symbols (Union[str, List[str]]): Single option symbol or list of option symbols
        (e.g., 'AAPL250613P00205000')
    feed (Optional[OptionsFeed]): The source feed of the data (opra or indicative).
        Default: opra if the user has the options subscription, indicative otherwise.

Returns:
    str: Formatted string containing a comprehensive snapshot including:
        - Symbol Information
        - Latest Quote:
            * Bid/Ask Prices and Sizes
            * Exchange Information
            * Trade Conditions
            * Tape Information
            * Timestamp (UTC)
        - Latest Trade:
            * Price and Size
            * Exchange and Conditions
            * Trade ID
            * Timestamp (UTC)
        - Implied Volatility (as percentage)
        - Greeks:
            * Delta (directional risk)
            * Gamma (delta sensitivity)
            * Rho (interest rate sensitivity)
            * Theta (time decay)
            * Vega (volatility sensitivity)

place_option_market_order

Places a market order for options (single or multi-leg) and returns the order details.
Supports up to 4 legs for multi-leg orders.

Single vs Multi-Leg Orders:
- Single-leg: One option contract (buy/sell call or put). Uses "simple" order class.
- Multi-leg: Multiple option contracts executed together as one strategy (spreads, straddles, etc.). Uses "mleg" order class.

API Processing:
- Single-leg orders: Sent as standard MarketOrderRequest with symbol and side
- Multi-leg orders: Sent as MarketOrderRequest with legs array for atomic execution

Args:
    legs (List[Dict[str, Any]]): List of option legs, where each leg is a dictionary containing:
        - symbol (str): Option contract symbol (e.g., 'AAPL230616C00150000')
        - side (str): 'buy' or 'sell'
        - ratio_qty (int): Quantity ratio for the leg (1-4)
    order_class (Optional[Union[str, OrderClass]]): Order class ('simple', 'bracket', 'oco', 'oto', 'mleg' or OrderClass enum)
        Defaults to 'simple' for single leg, 'mleg' for multi-leg
    quantity (int): Base quantity for the order (default: 1)
    time_in_force (TimeInForce): Time in force for the order. For options trading, 
        only DAY is supported (default: TimeInForce.DAY)
    extended_hours (bool): Whether to allow execution during extended hours (default: False)

Returns:
    str: Formatted string containing order details or error message

Examples:
    # Single-leg: Buy 1 call option
    legs = [{"symbol": "AAPL230616C00150000", "side": "buy", "ratio_qty": 1}]
    
    # Multi-leg: Bull call spread (executed atomically)
    legs = [
        {"symbol": "AAPL230616C00150000", "side": "buy", "ratio_qty": 1},
        {"symbol": "AAPL230616C00160000", "side": "sell", "ratio_qty": 1}
    ]

Note:
    Some option strategies may require specific account permissions:
    - Level 1: Covered calls, Covered puts, Cash-Secured put, etc.
    - Level 2: Long calls, Long puts, cash-secured puts, etc.
    - Level 3: Spreads and combinations: Butterfly Spreads, Straddles, Strangles, Calendar Spreads (except for short call calendar spread, short strangles, short straddles)
    - Level 4: Uncovered options (naked calls/puts), Short Strangles, Short Straddles, Short Call Calendar Spread, etc.
    If you receive a permission error, please check your account's option trading level.