Alpaca's Official MCP Server

by alpacahq

498 downloads Not rated yet
GitHub

About

Alpaca’s official MCP Server lets you trade stocks, ETFs, crypto, and options, run data analysis, and build strategies in plain English directly from your favorite LLM tools and IDEs

Explore

- Market Data
- Real-time quotes, trades, and price bars for stocks, crypto, and options
- Historical data with flexible timeframes (1Min to 1Month)
- Comprehensive stock snapshots and trade-level history
- Option contract quotes and Greeks
- Account Management
- View balances, buying power, and account status
- Inspect all open and closed positions
- Position Management
- Get detailed info on individual holdings
- Liquidate all or partial positions by share count or percentage
- Order Management
- Place stocks, ETFs, crypto, and options orders
- Support for market, limit, stop, stop-limit, and trailing-stop orders
- Cancel orders individually or in bulk
- Retrieve full order history
- Options Trading
- Search option contracts by expiration, strike price, and type
- Place single-leg or multi-leg options strategies (spreads, straddles, etc.)
- Get latest quotes, Greeks, and implied volatility
- Crypto Trading
- Place market, limit, and stop-limit crypto orders
- Support for GTC and IOC time in force
- Handle quantity or notional-based orders
- Market Status & Corporate Actions
- Check if markets are open
- Fetch market calendar and trading sessions
- View upcoming / historical corporate announcements (earnings, splits, dividends)
- Watchlist Management
- Create, update, and view personal watchlists
- Manage multiple watchlists for tracking assets
- Asset Search
- Query details for stocks, ETFs, crypto, and options
- Filter assets by status, class, exchange, and attributes
- OAuth 2.0 Support
- Authorization header passthrough for hosted MCP servers
- Multi-tenant support - each LLM chatbot request can use a different user's OAuth token
- Automatic detection of Authorization headers in incoming HTTP requests
- Seamlessly forwards authentication to Alpaca Trading API
- Backward compatible with traditional API key/secret authentication

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Alpaca's Official MCP Server
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

Prerequisites

You need the following prerequisites to configure and run the Alpaca MCP Server. - Terminal (macOS/Linux) | Command Prompt or PowerShell (Windows) - Python 3.10+ (Check the official installation guide and confirm the version by typing the following command: python3 --version in Terminal) - uv (Install using the official guide)\ Tip: uv can be installed either through a package manager (like Homebrew) or directly using curl | sh. - Alpaca Trading API keys (free paper trading account available) - MCP client (Claude Desktop, Cursor, VS Code, etc.) Note: Using an MCP server requires installation and configuration of both the MCP server and MCP client.

Install and configure

uvx alpaca-mcp-server init `` Note: If you don't have uv yet, install it first and then restart your terminal so uv/uvx are recognized. See the official guide: https://docs.astral.sh/uv/getting-started/installation/ Then add to your MCP client config : Config file locations: - Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows) - Cursor: ~/.cursor/mcp.json (Mac/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows) `json { "mcpServers": { "alpaca": { "command": "uvx", "args": ["alpaca-mcp-server", "serve"], "env": { "ALPACA_API_KEY": "your_alpaca_api_key", "ALPACA_SECRET_KEY": "your_alpaca_secret_key" } } } } ` </details> <details> <summary><b>Method 2: Install.py for Cursor or Claude Desktop</b></summary> Clone the repository and navigate to the directory: `bash git clone https://github.com/alpacahq/alpaca-mcp-server.git cd alpaca-mcp-server `` Execute the following commands in your termina

…

get_account_info

Retrieves and formats the current account information including balances and status. Returns: str: Account details with ID, status, buying power, cash, equity, and PDT status

get_all_positions

Retrieves and formats all current positions in the portfolio. Returns: str: List of positions with symbol, quantity, market value, entry/current price, and 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_asset

Retrieves and formats detailed information about a specific asset. Args: symbol (str): The symbol of the asset to get information for Returns: str: Asset details with name, exchange, class, status, and trading properties

get_all_assets

Get all available assets with optional filtering. Args: status (Optional[str]): Filter by asset status (e.g., 'active', 'inactive') asset_class (Optional[str]): Filter by asset class (e.g., 'us_equity', 'crypto') exchange (Optional[str]): Filter by exchange (e.g., 'NYSE', 'NASDAQ') attributes (Optional[str]): Comma-separated values for multiple attributes Returns: str: Formatted list of assets with symbol, name, exchange, class, and status

get_corporate_actions

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_portfolio_history

Retrieves account portfolio history (equity and P/L) over a requested time window. Args: timeframe (Optional[str]): Resolution of each data point (e.g., "1Min", "5Min", "15Min", "1H", "1D"). period (Optional[str]): Window length (e.g., "1W", "1M", "3M", "6M", "1Y", "all"). start (Optional[str]): Start time in ISO (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS). end (Optional[str]): End time in ISO (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS). date_end (Optional[str]): End date (alternative to end) as ISO date or datetime. intraday_reporting (Optional[str]): "market_hours", "extended_hours", or "continuous". pnl_reset (Optional[str]): P/L reset behavior (e.g., "daily", "weekly", "no_reset"). extended_hours (Optional[bool]): Include extended hours where applicable. cashflow_types (Optional[List[str]]): Optional cashflow categories to include. Returns: str: JSON string with keys: timestamp, equity, profit_loss, profit_loss_pct, base_value, timeframe, and optional cashflow.

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. Returns: str: List of watchlists with name, ID, and timestamps

update_watchlist_by_id

Update an existing watchlist. Args: watchlist_id (str): The UUID of the watchlist to update name (str): New name for the watchlist symbols (List[str]): New list of symbols for the watchlist Returns: str: Confirmation message with updated watchlist name

get_watchlist_by_id

Get a specific watchlist by its ID. Args: watchlist_id (str): The UUID of the watchlist Returns: str: Watchlist details including name, ID, timestamps, and symbols

add_asset_to_watchlist_by_id

Add an asset by symbol to a specific watchlist. Args: watchlist_id (str): The UUID of the watchlist symbol (str): The asset symbol to add (e.g., 'AAPL') Returns: str: Confirmation with updated watchlist symbols

remove_asset_from_watchlist_by_id

Remove an asset by symbol from a specific watchlist. Args: watchlist_id (str): The UUID of the watchlist symbol (str): The asset symbol to remove (e.g., 'AAPL') Returns: str: Confirmation with updated watchlist symbols

delete_watchlist_by_id

Delete a specific watchlist by its ID. Args: watchlist_id (str): The UUID of the watchlist to delete Returns: str: Confirmation message on successful deletion

get_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_clock

Retrieves and formats current market status and next open/close times. Returns: str: Market status with current time, open/closed state, and next open/close times

get_stock_bars

Retrieves and formats historical price bars for a stock with configurable timeframe and time range. Args: symbol (Union[str, List[str]]): Stock ticker symbol(s) (e.g., 'AAPL', 'MSFT' or ['AAPL', 'MSFT']) days (int): Number of days to look back (default: 5, ignored if start is provided) hours (int): Number of hours to look back (default: 0, ignored if start is provided) minutes (int): Number of minutes to look back (default: 30, ignored if start is provided) timeframe (str): Bar timeframe - supports flexible Alpaca's formats: - Minutes: "1Min" to "59Min" (or "1T" to "59T"), e.g., "5Min", "15Min", "30Min" - Hours: "1Hour" to "23Hour" (or "1H" to "23H"), e.g., "1Hour", "4Hour", "6Hour" - Days: "1Day" (or "1D") - Weeks: "1Week" (or "1W") - Months: "1Month", "2Month", "3Month", "4Month", "6Month", or "12Month" (or use "M" suffix) (default: "1Day") limit (Optional[int]): Maximum number of bars to return (default: 1000) 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") sort (Optional[Sort]): Chronological order of response (ASC or DESC, default: ASC) feed (Optional[DataFeed]): The stock data feed to retrieve from (DataFeed.IEX or DataFeed.SIP, default: None) currency (Optional[SupportedCurrencies]): Currency for prices (default: USD) asof (Optional[str]): The asof date in YYYY-MM-DD format tz (str): Timezone for naive datetime strings (default: "America/New_York") Supported: "UTC", "ET", "EST", "EDT", "America/New_York" Returns: str: Formatted string containing historical price data with timestamps, OHLCV data

get_stock_quotes

Retrieves and formats historical quote data (level 1 bid/ask) for a stock. Args: symbol (Union[str, List[str]]): Stock ticker symbol(s) (e.g., 'AAPL', 'MSFT' or ['AAPL', 'MSFT']) days (int): Number of days to look back (default: 0, ignored if start is provided) hours (int): Number of hours to look back (default: 0, ignored if start is provided) minutes (int): Number of minutes to look back (default: 20, ignored if start is provided) limit (Optional[int]): Upper limit of number of data points to return (default: 1000) 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") sort (Optional[Sort]): Chronological order of response (ASC or DESC) feed (Optional[DataFeed]): The stock data feed to retrieve from (DataFeed.IEX or DataFeed.SIP, default: None) currency (Optional[SupportedCurrencies]): Currency for prices (default: USD) asof (Optional[str]): The asof date in YYYY-MM-DD format tz (str): Timezone for naive datetime strings (default: "America/New_York") Supported: "UTC", "ET", "EST", "EDT", "America/New_York" Returns: str: Formatted string containing quote summary or an error message

get_stock_trades

Retrieves and formats historical trades for a stock. Args: symbol (Union[str, List[str]]): Stock ticker symbol(s) (e.g., 'AAPL', 'MSFT' or ['AAPL', 'MSFT']) days (int): Number of days to look back (default: 0, ignored if start is provided) hours (int): Number of hours to look back (default: 0, ignored if start is provided) minutes (int): Number of minutes to look back (default: 30, ignored if start is provided) limit (Optional[int]): Upper limit of number of data points to return 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") sort (Optional[Sort]): Chronological order of response (ASC or DESC) feed (Optional[DataFeed]): The stock data feed to retrieve from (DataFeed.IEX or DataFeed.SIP, default: None) currency (Optional[SupportedCurrencies]): Currency for prices (default: USD) asof (Optional[str]): The asof date in YYYY-MM-DD format tz (str): Timezone for naive datetime strings (default: "America/New_York") Supported: "UTC", "ET", "EST", "EDT", "America/New_York" Returns: str: Formatted string containing trade history or an error message

get_stock_latest_bar

Get the latest minute bar for one or more stocks. Args: symbol_or_symbols: Stock ticker symbol(s) (e.g., 'AAPL' or ['AAPL', 'MSFT']) feed: The stock data feed to retrieve from (DataFeed.IEX or DataFeed.SIP, default: None) currency: The currency for prices (optional, defaults to USD) Returns: A formatted string containing the latest bar details or an error message

get_stock_latest_quote

Retrieves and formats the latest quote for one or more stocks. Args: symbol_or_symbols (Union[str, List[str]]): Stock ticker symbol(s) (e.g., 'AAPL' or ['AAPL', 'MSFT']) feed (Optional[DataFeed]): Data feed source (IEX or SIP) currency (Optional[SupportedCurrencies]): Currency for prices (default: USD) Returns: str: Latest bid/ask prices, sizes, and timestamp for each symbol

get_stock_latest_trade

Get the latest trade for one or more stocks. Args: symbol_or_symbols: Stock ticker symbol(s) (e.g., 'AAPL' or ['AAPL', 'MSFT']) feed: The stock data feed to retrieve from (DataFeed.IEX or DataFeed.SIP, default: None) currency: The currency for prices (optional, defaults to USD) Returns: A formatted string containing the latest trade 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 (DataFeed.IEX or DataFeed.SIP, default: None) 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_crypto_bars

Retrieves and formats historical price bars for a cryptocurrency with configurable timeframe and time range. Args: symbol (Union[str, List[str]]): Crypto symbol(s) (e.g., 'BTC/USD', 'ETH/USD' or ['BTC/USD', 'ETH/USD']) days (int): Number of days to look back (default: 1, ignored if start is provided) hours (int): Number of hours to look back (default: 0, ignored if start is provided) minutes (int): Number of minutes to look back (default: 30, ignored if start is provided) timeframe (str): Bar timeframe - supports flexible Alpaca's 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: "1Hour") 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") feed (CryptoFeed): The crypto data feed to retrieve from (default: US) tz (str): Timezone for naive datetime strings (default: "America/New_York") Supported: "UTC", "ET", "EST", "EDT", "America/New_York" Returns: str: Formatted string containing historical crypto price data with timestamps, OHLCV data

get_crypto_quotes

Retrieves and formats historical quote data for a cryptocurrency. Args: symbol (Union[str, List[str]]): Crypto symbol(s) (e.g., 'BTC/USD', 'ETH/USD' or ['BTC/USD', 'ETH/USD']) days (int): Number of days to look back (default: 0, ignored if start is provided) hours (int): Number of hours to look back (default: 0, ignored if start is provided) minutes (int): Number of minutes to look back (default: 15, ignored if start is provided) limit (Optional[int]): Maximum number of quotes 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") feed (CryptoFeed): The crypto data feed to retrieve from (default: US) tz (str): Timezone for naive datetime strings (default: "America/New_York") Supported: "UTC", "ET", "EST", "EDT", "America/New_York" Returns: str: Formatted string containing historical crypto quote data with timestamps, bid/ask prices and sizes

get_crypto_trades

Retrieves and formats historical trade prints for a cryptocurrency. Args: symbol (Union[str, List[str]]): Crypto symbol(s) (e.g., 'BTC/USD' or ['BTC/USD','ETH/USD']) days (int): Number of days to look back (default: 0, ignored if start is provided) hours (int): Number of hours to look back (default: 0, ignored if start is provided) minutes (int): Number of minutes to look back (default: 15, ignored if start is provided) limit (Optional[int]): Maximum number of trades to return start (Optional[str]): ISO start time (e.g., "2023-01-01T09:30:00") end (Optional[str]): ISO end time (e.g., "2023-01-01T16:00:00") sort (Optional[str]): 'asc' or 'desc' chronological order feed (CryptoFeed): Crypto data feed (default: US) tz (str): Timezone for naive datetime strings (default: "America/New_York") Supported: "UTC", "ET", "EST", "EDT", "America/New_York" Returns: str: Formatted trade history

get_crypto_latest_bar

Returns the latest minute bar for one or more crypto symbols.

get_crypto_latest_quote

Returns the latest quote for one or more crypto symbols. Args: symbol (Union[str, List[str]]): Crypto symbol(s) (e.g., 'BTC/USD' or ['BTC/USD','ETH/USD']) feed (CryptoFeed): The crypto data feed (default: US) Returns: str: Formatted latest quote(s)

get_crypto_latest_trade

Returns the latest trade for one or more crypto symbols.

get_crypto_snapshot

Returns a snapshot for one or more crypto symbols including latest trade, quote, minute bar, daily bar, and previous daily bar. Args: symbol (Union[str, List[str]]): Crypto symbol(s) (e.g., 'BTC/USD' or ['BTC/USD', 'ETH/USD']) feed (CryptoFeed): Data feed source (default: US) Returns: str: Snapshot with latest quote, trade, and OHLCV bars for each symbol

get_crypto_latest_orderbook

Returns the latest orderbook for one or more crypto symbols.

get_option_contracts

Retrieves option contracts for underlying symbol(s). Args: underlying_symbols (Union[str, List[str]]): Underlying asset symbol(s) (e.g., 'SPY', 'AAPL') expiration_date (Optional[date]): Specific expiration date expiration_date_gte (Optional[date]): Minimum expiration date expiration_date_lte (Optional[date]): Maximum expiration date expiration_expression (Optional[str]): Natural language (e.g., "week of September 2, 2025") strike_price_gte (Optional[str]): Minimum strike price strike_price_lte (Optional[str]): Maximum strike price contract_type (Optional[str]): Filter by 'call' or 'put' status (Optional[AssetStatus]): Filter by status (default: 'active') root_symbol (Optional[str]): Filter by root symbol limit (Optional[int]): Maximum number of contracts to return Returns: str: List of option contracts with symbol, strike, expiration, type, and status Examples: get_option_contracts("NVDA", expiration_expression="week of September 2, 2025") get_option_contracts(["SPY", "AAPL"], expiration_date_gte=date(2025,9,1), expiration_date_lte=date(2025,9,5))

get_option_latest_quote

Retrieves and formats the latest quote for one or more option contracts. This endpoint returns real-time pricing and market data, including bid/ask prices, sizes, and exchange information. Args: symbol_or_symbols (Union[str, List[str]]): Option contract symbol(s) (e.g., 'AAPL230616C00150000' or ['AAPL230616C00150000', 'MSFT230616P00300000']) feed (Optional[OptionsFeed]): Data feed source (OptionsFeed.OPRA or OptionsFeed.INDICATIVE) Default: OptionsFeed.OPRA if the user has the options subscription, OptionsFeed.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. Args: symbol_or_symbols (Union[str, List[str]]): Option symbol(s) (e.g., 'AAPL250613P00205000') feed (Optional[OptionsFeed]): Data feed source (OPRA or INDICATIVE) Returns: str: Snapshot with quote, trade, implied volatility, and Greeks for each contract

get_option_chain

Retrieves option chain data for an underlying symbol, including latest trade, quote, implied volatility, and greeks for each contract. Args: underlying_symbol (str): The underlying symbol (e.g., 'AAPL', 'SPY') feed (Optional[OptionsFeed]): Data feed source (OPRA or INDICATIVE) (default: OPRA if the user has the options subscription, INDICATIVE otherwise) contract_type (Optional[str]): Filter by contract type ('call', 'put', or None for both) strike_price_gte (Optional[float]): Minimum strike price filter strike_price_lte (Optional[float]): Maximum strike price filter expiration_date (Optional[Union[date, str]]): Exact expiration date (YYYY-MM-DD) expiration_date_gte (Optional[Union[date, str]]): Minimum expiration date expiration_date_lte (Optional[Union[date, str]]): Maximum expiration date root_symbol (Optional[str]): Filter by root symbol limit (Optional[int]): Max snapshots to return (1-1000, default 100) Returns: str: Formatted option chain with quote, trade, IV, and greeks for each contract

get_orders

Retrieves and formats orders with the specified filters. Args: status (str): Order status filter (open, closed, all) limit (int): Max orders to return (default: 10, max: 500) after (Optional[str]): Orders after this timestamp (ISO format) until (Optional[str]): Orders until this timestamp (ISO format) direction (Optional[str]): Sort order (asc or desc) nested (Optional[bool]): Roll up multi-leg orders under legs field side (Optional[str]): Filter by side (buy or sell) symbols (Optional[List[str]]): Filter by symbols Returns: str: Order details with symbol, type, side, quantity, status, and fill info

place_stock_order

Places a stock order using the specified order type and parameters. Args: symbol (str): Stock ticker symbol (e.g., 'AAPL', 'MSFT') side (str): Order side ('buy' or 'sell') quantity (float): Number of shares to trade type (str): Order type ('market', 'limit', 'stop', 'stop_limit', 'trailing_stop') time_in_force (Union[str, TimeInForce]): Time in force ('day', 'gtc', 'opg', 'cls', 'ioc', 'fok' or TimeInForce enum) order_class (Union[str, OrderClass]): Order class ('simple', 'bracket', 'oco', 'oto' or OrderClass enum) limit_price (Optional[float]): Limit price (required for LIMIT, STOP_LIMIT) stop_price (Optional[float]): Stop price (required for STOP, STOP_LIMIT) trail_price (Optional[float]): Trail price (for TRAILING_STOP) trail_percent (Optional[float]): Trail percent (for TRAILING_STOP) extended_hours (bool): Allow extended hours execution client_order_id (Optional[str]): Custom order identifier Returns: str: Order confirmation with details or error message

place_crypto_order

Place a crypto order (market, limit, stop_limit) with GTC/IOC time in force. Rules: - Market: require exactly one of qty or notional - Limit: require qty and limit_price (notional not supported) - Stop Limit: require qty, stop_price and limit_price (notional not supported) - time_in_force: only GTC or IOC are supported for crypto orders Args: symbol (str): Crypto symbol (e.g., 'BTC/USD', 'ETH/USD') side (str): Order side ('buy' or 'sell') order_type (str): Order type ('market', 'limit', 'stop_limit') time_in_force (Union[str, TimeInForce]): Time in force ('GTC' or 'IOC') qty (Optional[float]): Quantity to trade notional (Optional[float]): Notional value (market orders only) limit_price (Optional[float]): Limit price (required for limit/stop_limit) stop_price (Optional[float]): Stop price (required for stop_limit) client_order_id (Optional[str]): Custom order identifier Returns: str: Order confirmation with order ID, status, and execution details

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 (Union[str, TimeInForce]): Time in force ('day' or TimeInForce.DAY - only DAY is supported for options) 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.

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. This method will throw an error if the position does not exist! 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

exercise_options_position

Exercises a held option contract, converting it into the underlying asset. Args: symbol_or_contract_id (str): Option contract symbol (e.g., 'NVDA250919C001680') or contract ID Returns: str: Success message or error details

<details open>
<summary><b>Account & Positions</b></summary>

get_account_info() – View balance, margin, and account status
get_all_positions() – List all held assets
get_open_position(symbol) – Detailed info on a specific position

</details>
<details>
<summary><b>Assets</b></summary>

get_asset(symbol) – Search asset metadata
get_all_assets(status=None, asset_class=None, exchange=None, attributes=None) – List all tradable instruments with filtering options

</details>
<details>
<summary><b>Corporate Actions</b></summary>

get_corporate_actions(ca_types=None, start=None, end=None, symbols=None, cusips=None, ids=None, limit=1000, sort="asc") – Historical and future corporate actions (e.g., earnings, dividends, splits)

</details>
<details>
<summary><b>Portfolio</b></summary>

get_portfolio_history(timeframe=None, period=None, start=None, end=None, date_end=None, intraday_reporting=None, pnl_reset=None, extended_hours=None, cashflow_types=None) – Retrieve account portfolio history with equity and P/L over time

</details>
<details>
<summary><b>Watchlists</b></summary>

create_watchlist(name, symbols) – Create a new list
get_watchlists() – Retrieve all saved watchlists
update_watchlist_by_id(watchlist_id, name=None, symbols=None) – Modify an existing list
get_watchlist_by_id(watchlist_id) – Get a specific watchlist by its ID
add_asset_to_watchlist_by_id(watchlist_id, symbol) – Add an asset to a watchlist
remove_asset_from_watchlist_by_id(watchlist_id, symbol) – Remove an asset from a watchlist
delete_watchlist_by_id(watchlist_id) – Delete a specific watchlist

</details>
<details>
<summary><b>Market Calendar & Clock</b></summary>

get_calendar(start_date, end_date) – Holidays and trading days
get_clock() – Market open/close schedule and current status

</details>
<details>
<summary><b>Stock Market Data</b></summary>

get_stock_bars(symbol, days=5, hours=0, minutes=15, timeframe="1Day", limit=1000, start=None, end=None, sort=Sort.ASC, feed=None, currency=None, asof=None) – OHLCV historical bars with flexible timeframes (1Min, 5Min, 1Hour, 1Day, etc.)
get_stock_quotes(symbol, days=1, hours=0, minutes=15, limit=1000, sort=Sort.ASC, feed=None, currency=None, asof=None) – Historical quote data (level 1 bid/ask) for a stock
get_stock_trades(symbol, days=1, minutes=15, hours=0, limit=1000, sort=Sort.ASC, feed=None, currency=None, asof=None) – Trade-level history
get_stock_latest_bar(symbol, feed=None, currency=None) – Most recent OHLC bar
get_stock_latest_quote(symbol_or_symbols, feed=None, currency=None) – Real-time bid/ask quote for one or more symbols
get_stock_latest_trade(symbol, feed=None, currency=None) – Latest market trade price
get_stock_snapshot(symbol_or_symbols, feed=None, currency=None) – Comprehensive snapshot with latest quote, trade, minute bar, daily bar, and previous daily bar

</details>
<details>
<summary><b>Crypto Market Data</b></summary>

get_crypto_bars(symbol_or_symbols, days=1, timeframe="1Hour", limit=None, start=None, end=None, feed=CryptoFeed.US) – Historical price bars for cryptocurrency with configurable timeframe
get_crypto_quotes(symbol_or_symbols, days=3, limit=None, start=None, end=None, feed=CryptoFeed.US) – Historical quote data (bid/ask) for crypto
get_crypto_trades(symbol_or_symbols, days=1, limit=None, start=None, end=None, sort=None, feed=CryptoFeed.US) – Historical trade prints for cryptocurrency
get_crypto_latest_quote(symbol_or_symbols, feed=CryptoFeed.US) – Latest quote for one or more crypto symbols
get_crypto_latest_bar(symbol_or_symbols, feed=CryptoFeed.US) – Latest minute bar for crypto
get_crypto_latest_trade(symbol_or_symbols, feed=CryptoFeed.US) – Latest trade for crypto
get_crypto_snapshot(symbol_or_symbols, feed=CryptoFeed.US) – Comprehensive crypto snapshot including latest trade, quote, minute bar, daily and previous daily bars
get_crypto_latest_orderbook(symbol_or_symbols, feed=CryptoFeed.US) – Latest orderbook for crypto

</details>
<details>
<summary><b>Options Market Data</b></summary>

get_option_contracts(underlying_symbol, expiration_date=None, expiration_date_gte=None, expiration_date_lte=None, expiration_expression=None, strike_price_gte=None, strike_price_lte=None, type=None, status=None, root_symbol=None, limit=None) – Get option contracts with flexible filtering
get_option_latest_quote(option_symbol, feed=None) – Latest bid/ask on contract
get_option_snapshot(symbol_or_symbols, feed=None) – Get Greeks and underlying

</details>
<details>
<summary><b>Trading (Orders)</b></summary>

get_orders(status=None, limit=None, after=None, until=None, direction=None, nested=None, side=None, symbols=None) – Retrieve all or filtered orders
place_stock_order(symbol, side, quantity, order_type="market", limit_price=None, stop_price=None, trail_price=None, trail_percent=None, time_in_force="day", extended_hours=False, client_order_id=None) – Place a stock order of any type (market, limit, stop, stop_limit, trailing_stop)
place_crypto_order(symbol, side, order_type="market", time_in_force="gtc", qty=None, notional=None, limit_price=None, stop_price=None, client_order_id=None) – Place a crypto order supporting market, limit, and stop_limit types with GTC/IOC time in force
place_option_market_order(legs, order_class=None, quantity=1, time_in_force="day", extended_hours=False) – Execute option strategy (single or multi-leg)

</details>
<details>
<summary><b>Trading (Position Management)</b></summary>

cancel_all_orders() – Cancel all open orders
cancel_order_by_id(order_id) – Cancel a specific order
close_position(symbol, qty=None, percentage=None) – Close part or all of a position
close_all_positions(cancel_orders=False) – Liquidate entire portfolio

  • exercise_options_position(symbol_or_contract_id) – Exercise a held option contract, converting it into the underlying asset


</details>

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "alpaca's official mcp server": {
            "alpaca": {
                "command": "uvx",
                "args": [
                    "alpaca-mcp-server",
                    "serve"
                ],
                "env": {
                    "ALPACA_API_KEY": "your_alpaca_api_key",
                    "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
                }
            }
        }
    }
}

McpServers

{
    "alpaca": {
        "command": "uvx",
        "args": [
            "alpaca-mcp-server",
            "serve"
        ],
        "env": {
            "ALPACA_API_KEY": "your_alpaca_api_key",
            "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
        }
    }
}

<p align="center">
Alpaca logo
</p>

<div align="center">

<a href="https://x.com/alpacahq?lang=en" target="_blank">X</a>
<a href="https://www.reddit.com/r/alpacamarkets/" target="_blank">Reddit</a>
<a href="https://alpaca.markets/slack" target="_blank">Slack</a>
<a href="https://www.linkedin.com/company/alpacamarkets/" target="_blank">LinkedIn</a>
<a href="https://forum.alpaca.markets/" target="_blank">Forum</a>
<a href="https://docs.alpaca.markets/docs/getting-started" target="_blank">Docs</a>
<a href="https://alpaca.markets/sdks/python/" target="_blank">Python SDK</a>

</div>

<p align="center">
A comprehensive Model Context Protocol (MCP) server for Alpaca's Trading API. Enable natural language trading operations through AI assistants like Claude, Cursor, and VS Code. Supports stocks, options, crypto, portfolio management, and real-time market data.
</p>

Table of Contents



- Prerequisites
- Start here
- Getting Your API Keys
- Switching API Keys for Live Trading
- Quick Local Installation for MCP Server
- Features
- Example Prompts
- Example Outputs
- Available Tools
- MCP Client Configuration
- OAuth Bearer Token Support
- HTTP Transport for Remote Usage
- Disclosure

Prerequisites


You need the following prerequisites to configure and run the Alpaca MCP Server.
- Terminal (macOS/Linux) | Command Prompt or PowerShell (Windows)
- Python 3.10+ (Check the official installation guide and confirm the version by typing the following command: python3 --version in Terminal)
- uv (Install using the official guide)\
Tip: uv can be installed either through a package manager (like Homebrew) or directly using curl | sh.
- Alpaca Trading API keys (free paper trading account available)
- MCP client (Claude Desktop, Cursor, VS Code, etc.)

Note: Using an MCP server requires installation and configuration of both the MCP server and MCP client.

Start here


Note: These steps assume all Prerequisites have been installed.
- Claude Desktop
- Local: Use uvx or install.py → see Claude Desktop Configuration
- Claude Mobile
- Remote Hosting: Deploy to cloud service → see Claude Mobile Configuration
- ChatGPT
- Remote Hosting: Deploy to cloud service → see ChatGPT Configuration
- Cursor
- Local (Cursor Directory): Use the Cursor Directory entry and connect in a few clicks → see Cursor Configuration
- Local (install.py): Use install.py to set up and auto-configure Cursor → see Cursor Configuration
- VS Code
- Local: Use uvx → see VS Code Configuration
- PyCharm
- Local: Use uvx → see PyCharm Configuration
- Claude Code
- Local: Use uvx or Docker → see Claude Code Configuration
- Gemini CLI
- Local: Use uvx → see Gemini CLI Configuration

Note: How to show hidden files
- macOS Finder: Command + Shift + .
- Linux file managers: Ctrl + H
- Windows File Explorer: Alt, V, H
- Terminal (macOS/Linux): ls -a

Getting Your API Keys



1. Visit Alpaca Trading API Account Dashboard
2. Create a free paper trading account
3. Generate API keys from the dashboard

Switching API Keys for Live Trading



To enable live trading with real funds or switch between different accounts, update API credentials in two places:

1. .env file (used by MCP server)
2. MCP client config JSON (used by MCP client like Claude Desktop, Cursor, etc.)

Important: The MCP client configuration overrides the .env file. When using an MCP client, the credentials in the client's JSON config take precedence.

<details>
<summary><b>Step 1: Update MCP Server Config .env file</b></summary>

Method 1: Run the init command again to update your .env file
``bash

Follow the prompts to update your keys and toggle paper/live trading


uvx alpaca-mcp-server init
`
Method 2: Manually Update

`
ALPACA_API_KEY = "your_alpaca_api_key_for_live_account"
ALPACA_SECRET_KEY = "your_alpaca_secret_key_for_live_account"
ALPACA_PAPER_TRADE = False
TRADE_API_URL = None
TRADE_API_WSS = None
DATA_API_URL = None
STREAM_DATA_WSS = None
`
</details>

<details>
<summary><b>Step 2: Update MCP Client Config Json file</b></summary>

Step 2-1: Edit your MCP client configuration file:
- Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
- Cursor:
~/.cursor/mcp.json
- VS Code:
.vscode/mcp.json (workspace) or user settings.json

Step 2-2: Update the API keys in the
env section:

For uvx installations:
`json
{
"mcpServers": {
"alpaca": {
"command": "uvx",
"args": ["alpaca-mcp-server", "serve"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key_for_live_account",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key_for_live_account"
}
}
}
}
`
Then, restart your MCP client (Claude Desktop, Cursor, etc.)
</details>

Quick Local Installation for MCP Server


<details>
<summary><b>Method 1: One-click installation with uvx from PyPI</b></summary>

Note: Using an MCP server requires installation and configuration of both the MCP server and MCP client.

`bash

Install and configure


uvx alpaca-mcp-server init
`

Note: If you don't have
uv yet, install it first and then restart your terminal so uv/uvx are recognized. See the official guide: https://docs.astral.sh/uv/getting-started/installation/

Then add to your MCP client config :

Config file locations:
- Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
- Cursor:
~/.cursor/mcp.json (Mac/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows)


`json
{
"mcpServers": {
"alpaca": {
"command": "uvx",
"args": ["alpaca-mcp-server", "serve"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
`

</details>

<details>
<summary><b>Method 2: Install.py for Cursor or Claude Desktop</b></summary>

Clone the repository and navigate to the directory:
`bash
git clone https://github.com/alpacahq/alpaca-mcp-server.git
cd alpaca-mcp-server
``
Execute the following commands in your termina

…

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.