alpaca-trading-mcp

# Alpaca Trading MCP > Skill by [ara.so](https://ara.so) — MCP Skills collection. Alpaca MCP Server is an official Model Context Protocol server that enables natural language trading operations through AI assistants. It provides comprehensive access to Alpaca's Trading API for stocks, options, crypto, portfolio management, and real-time market data. Built with FastMCP and OpenAPI, this is a complete v2 rewrite with spec-aligned tooling. ## What It Does - **Market Data Access**: Real-time and historical quotes, trades, bars for stocks, crypto, and options - **Trading Operations**: Place market, limit, stop, trailing-stop orders for any supported asset - **Options Trading**: Search contracts, place single/multi-leg strategies, get Greeks and IV - **Portfolio Management**: View account info, positions, buying power, portfolio history - **Watchlist Management**: Create, update, and manage custom watchlists - **News & Corporate Actions**: Access market news and corporate action announcements ## Installation ### Prerequisites - Python 3.10+ - uv package manager: `curl -LsSf https://astral.sh/uv/install.sh | sh` - Alpaca API keys (free paper trading account at https://app.alpaca.markets) - An MCP-compatible client (Claude Desktop, Cursor, VS Code, etc.) ### Configuration Add to your MCP client configuration file: **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac): ```json { "mcpServers": { "alpaca": { "command": "uvx", "args": ["alpaca-mcp-server"], "env": { "ALPACA_API_KEY": "your_alpaca_api_key", "ALPACA_SECRET_KEY": "your_alpaca_secret_key", "ALPACA_PAPER_TRADE": "true" } } } } ``` **Cursor** (`~/.cursor/mcp.json`): ```json { "mcpServers": { "alpaca": { "command": "uvx", "args": ["alpaca-mcp-server"], "env": { "ALPACA_API_KEY": "your_alpaca_api_key", "ALPACA_SECRET_KEY": "your_alpaca_secret_key", "ALPACA_PAPER_TRADE": "true" } } } } ``` **VS Code** (`.vscode/mcp.json` in project root): ```json { "mcp": { "servers": { "alpaca": { "type": "stdio", "command": "uvx", "args": ["alpaca-mcp-server"], "env": { "ALPACA_API_KEY": "your_alpaca_api_key", "ALPACA_SECRET_KEY": "your_alpaca_secret_key", "ALPACA_PAPER_TRADE": "true" } } } } } ``` **Claude Code CLI**: ```bash claude mcp add alpaca --scope user --transport stdio uvx alpaca-mcp-server \ --env ALPACA_API_KEY=your_alpaca_api_key \ --env ALPACA_SECRET_KEY=your_alpaca_secret_key \ --env ALPACA_PAPER_TRADE=true ``` ### Environment Variables | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `ALPACA_API_KEY` | Yes | — | Your Alpaca API key | | `ALPACA_SECRET_KEY` | Yes | — | Your Alpaca secret key | | `ALPACA_PAPER_TRADE` | No | `true` | Set to `false` for live trading | | `ALPACA_TOOLSETS` | No | all | Comma-separated toolsets to enable | ### Toolset Filtering Restrict available tools by setting `ALPACA_TOOLSETS`: ```json { "env": { "ALPACA_TOOLSETS": "account,trading,stock-data" } } ``` Available toolsets: - `account`: Account info, portfolio history, activities - `trading`: Orders, positions, options exercise - `watchlists`: Watchlist CRUD operations - `assets`: Asset lookup, option contracts, market calendar - `stock-data`: Stock bars, quotes, trades, snapshots - `crypto-data`: Crypto bars, quotes, trades, orderbooks - `options-data`: Option bars, quotes, Greeks, chain - `corporate-actions`: Corporate action announcements - `news`: News articles ## Core Trading Operations ### Check Account Status ```python # Natural language prompts: # "What's my current account balance?" # "Show my buying power" # "Am I approved for options trading?" # The MCP server exposes get_account_info tool # Returns: account_number, status, buying_power, cash, portfolio_value, etc. ``` ### Place Stock Orders ```python # Natural language prompts: # "Buy 100 shares of AAPL at market price" # "Place a limit order to buy TSLA at $250" # "Sell 50 shares of NVDA with a trailing stop at 2%" # Market order # Tool: post_orders # Parameters: { # "symbol": "AAPL", # "qty": 100, # "side": "buy", # "type": "market", # "time_in_force": "day" # } # Limit order # Parameters: { # "symbol": "TSLA", # "qty": 10, # "side": "buy", # "type": "limit", # "limit_price": 250.00, # "time_in_force": "gtc" # } # Trailing stop # Parameters: { # "symbol": "NVDA", # "qty": 50, # "side": "sell", # "type": "trailing_stop", # "trail_percent": 2.0, # "time_in_force": "gtc" # } ``` ### Get Real-Time Market Data ```python # Natural language prompts: # "What's the current price of AAPL?" # "Show me the latest BTC quote" # "Get today's price bars for MSFT in 5-minute intervals" # Latest quote # Tool: get_stocks_quotes_latest # Parameters: {"symbols": "AAPL,MSFT,GOOGL"} # Crypto quote # Tool: get_crypto_quotes_latest # Parameters: {"symbols": "BTC/USD,ETH/USD"} # Historical bars # Tool: get_stocks_bars # Parameters: { # "symbols": "MSFT", # "timeframe": "5Min", # "start": "2025-05-01T09:30:00Z", # "end": "2025-05-01T16:00:00Z" # } ``` ### Options Trading ```python # Natural language prompts: # "Find call options for AAPL expiring next month" # "Place a covered call on my 100 shares of NVDA" # "Get the Greeks for SPY 500 calls expiring this Friday" # Search option contracts # Tool: get_options_contracts # Parameters: { # "underlying_symbols": "AAPL", # "expiration_date_gte": "2025-06-01", # "expiration_date_lte": "2025-06-30", # "type": "call" # } # Place option order # Tool: post_orders # Parameters: { # "symbol": "AAPL250620C00150000", # "qty": 1, # "side": "sell_to_open", # "type": "limit", # "limit_price": 5.50, # "time_in_force": "day", # "class": "option" # } # Get option snapshot with Greeks # Tool: get_options_snapshots # Parameters: {"symbols": "SPY250516C00500000"} # Returns: greeks (delta, gamma, theta, vega), implied_volatility, latest_quote ``` ### Manage Positions ```python # Natural language prompts: # "Show all my open positions" # "What's my position in AAPL?" # "Close half of my TSLA position" # Get all positions # Tool: get_positions # Get specific position # Tool: get_positions_by_symbol_or_asset_id # Parameters: {"symbol_or_asset_id": "AAPL"} # Close position # Tool: delete_positions_by_symbol_or_asset_id # Parameters: { # "symbol_or_asset_id": "TSLA", # "percentage": 50 # Optional: close percentage # } ``` ### Watchlist Management ```python # Natural language prompts: # "Create a tech stocks watchlist with AAPL, MSFT, GOOGL" # "Add TSLA to my tech watchlist" # "Show me all my watchlists" # Create watchlist # Tool: post_watchlists # Parameters: { # "name": "Tech Stocks", # "symbols": ["AAPL", "MSFT", "GOOGL"] # } # Get all watchlists # Tool: get_watchlists # Add symbol to watchlist # Tool: post_watchlists_by_watchlist_id # Parameters: { # "watchlist_id": "uuid-here", # "symbol": "TSLA" # } ``` ## Advanced Market Data Queries ### Screen Stocks ```python # Natural language prompts: # "Find the most active stocks today" # "Show me top gainers with volume over 1M" # Tool: get_screener_stocks_most_actives # Parameters: { # "by": "volume", # "top": 10 # } # Tool: get_screener_stocks_movers # Parameters: { # "market_type": "stocks", # "top": 20 # } ``` ### Get News ```python # Natural language prompts: # "Show me latest news about AAPL" # "Get crypto news for Bitcoin" # Stock news # Tool: get_news # Parameters: { # "symbols": "AAPL", # "limit": 10, # "sort": "desc" # } # Crypto news # Tool: get_crypto_news # Parameters: { # "symbols": "BTC", # "limit": 10 # } ``` ### Corporate Actions ```python # Natural language prompts: # "Are there any upcoming stock splits?" # "Show dividend announcements for next week" # Tool: get_corporate_actions_announcements # Parameters: { # "ca_types": "dividend,split", # "since": "2025-05-01", # "until": "2025-05-31" # } ``` ## Portfolio Analysis ### Get Portfolio History ```python # Natural language prompts: # "Show my portfolio performance over the last month" # "Graph my portfolio value for the past year" # Tool: get_account_portfolio_history # Parameters: { # "period": "1M", # "timeframe": "1D" # } # Returns: timestamp, equity, profit_loss, profit_loss_pct arrays ``` ### Account Activities ```python # Natural language prompts: # "Show my recent trades" # "List all dividend payments this month" # Tool: get_account_activities # Parameters: { # "activity_types": "FILL,DIV", # "after": "2025-05-01T00:00:00Z", # "direction": "desc" # } ``` ## Common Patterns ### Multi-Symbol Quotes ```python # Get quotes for multiple symbols at once # "Get current prices for AAPL, MSFT, GOOGL, AMZN" # Tool: get_stocks_quotes_latest # Parameters: {"symbols": "AAPL,MSFT,GOOGL,AMZN"} # Use feed parameter for realtime: "feed": "sip" ``` ### Batch Order Placement ```python # Place multiple orders together # "Buy 10 shares each of AAPL, MSFT, GOOGL at market" # Call post_orders tool 3 times or use a loop pattern # Each order is submitted individually through the API ``` ### Conditional Order Logic ```python # Complex strategies require multiple steps # "If AAPL drops below $150, buy 100 shares" # 1. Monitor current price with get_stocks_quotes_latest # 2. When condition met, call post_orders # Note: Alpaca supports bracket/OCO orders natively: