alpaca-mcp-server-trading

# Alpaca MCP Server Trading > Skill by [ara.so](https://ara.so) — MCP Skills collection. ## Overview Alpaca MCP Server is an official Model Context Protocol server that enables AI assistants to trade stocks, ETFs, crypto, and options through natural language. Built with FastMCP and OpenAPI, it exposes Alpaca's Trading API as MCP tools in Claude Desktop, Cursor, VS Code, PyCharm, and other MCP clients. **Key capabilities:** - Real-time market data (quotes, trades, bars, snapshots) - Order management (market, limit, stop, trailing-stop orders) - Options trading (single-leg and multi-leg strategies) - Crypto trading (BTC, ETH, and more) - Account and portfolio management - Watchlists and corporate actions - Paper trading by default, live trading supported ## Installation ### Prerequisites - Python 3.10+ - [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager - Alpaca API keys (free paper trading account at [alpaca.markets](https://alpaca.markets)) ### Get API Keys 1. Sign up at [Alpaca Dashboard](https://app.alpaca.markets/paper/dashboard/overview) 2. Create a paper trading account 3. Generate API keys from the dashboard ### Configuration by MCP Client #### Claude Desktop Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "alpaca": { "command": "uvx", "args": ["alpaca-mcp-server"], "env": { "ALPACA_API_KEY": "your_alpaca_api_key", "ALPACA_SECRET_KEY": "your_alpaca_secret_key" } } } } ``` Restart Claude Desktop. #### Cursor Add to `~/.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" } } } } ``` Restart Cursor. #### VS Code Create `.vscode/mcp.json` in your project: ```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" } } } } } ``` Reload window. #### PyCharm 1. Go to File → Settings → Tools → Model Context Protocol (MCP) 2. Add new server: - Type: stdio - Command: `uvx` - Arguments: `alpaca-mcp-server` 3. Set environment variables: ``` ALPACA_API_KEY=your_alpaca_api_key ALPACA_SECRET_KEY=your_alpaca_secret_key ``` #### Docker ```bash git clone https://github.com/alpacahq/alpaca-mcp-server.git cd alpaca-mcp-server docker build -t mcp/alpaca:latest . ``` Add to MCP client config: ```json { "mcpServers": { "alpaca": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "ALPACA_API_KEY", "-e", "ALPACA_SECRET_KEY", "-e", "ALPACA_PAPER_TRADE=true", "mcp/alpaca:latest" ] } } } ``` ## Configuration All configuration is via environment variables in your MCP client config: | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `ALPACA_API_KEY` | Yes | — | Alpaca API key | | `ALPACA_SECRET_KEY` | Yes | — | Alpaca secret key | | `ALPACA_PAPER_TRADE` | No | `true` | Set to `false` for live trading | | `ALPACA_TOOLSETS` | No | all | Comma-separated toolsets to enable | ### Switching to Live Trading **⚠️ WARNING: Live trading uses real money. Test thoroughly in paper trading first.** Update env vars in your MCP client config: ```json { "env": { "ALPACA_API_KEY": "your_live_api_key", "ALPACA_SECRET_KEY": "your_live_secret_key", "ALPACA_PAPER_TRADE": "false" } } ``` Restart your MCP client. ### Toolset Filtering Limit the server to specific capabilities by setting `ALPACA_TOOLSETS`: ```json { "env": { "ALPACA_API_KEY": "your_alpaca_api_key", "ALPACA_SECRET_KEY": "your_alpaca_secret_key", "ALPACA_TOOLSETS": "stock-data,trading,account" } } ``` **Available toolsets:** - `account` — Account info, balances, portfolio history - `trading` — Orders, positions, option exercises - `watchlists` — Watchlist management - `assets` — Asset lookup, option contracts, market calendar - `stock-data` — Stock bars, quotes, trades, snapshots, screeners - `crypto-data` — Crypto bars, quotes, trades, orderbooks - `options-data` — Option bars, quotes, Greeks, chain data - `corporate-actions` — Corporate action announcements - `news` — News articles for stocks and crypto ## Common Usage Patterns ### Getting Account Information Natural language prompts that work: - "What's my account balance?" - "Show my portfolio history for the last week" - "What's my buying power?" The AI will use tools like `get_account_info` and `get_portfolio_history`. ### Trading Stocks **Market order:** ``` Buy 10 shares of AAPL at market price ``` **Limit order:** ``` Buy 5 shares of TSLA with a limit price of $250 ``` **Stop-loss:** ``` Sell 3 shares of NVDA with a stop price of $800 ``` **Bracket order:** ``` Buy 10 shares of GOOGL at market with a take-profit at $150 and stop-loss at $140 ``` ### Trading Crypto ``` Buy 0.1 BTC at market price ``` ``` Place a limit order to buy 1 ETH at $3000 ``` ### Trading Options **Find contracts:** ``` Show me call options for SPY expiring next Friday with strikes near $450 ``` **Place option trade:** ``` Buy 1 call option for AAPL with strike $180 expiring in 30 days ``` **Multi-leg strategy:** ``` Create an iron condor for SPY with the following legs: buy 1 put at $440, sell 1 put at $445, sell 1 call at $455, buy 1 call at $460, all expiring next Friday ``` ### Market Data **Real-time quote:** ``` Get the current price of AAPL ``` **Historical bars:** ``` Show me daily price bars for TSLA for the last month ``` **Snapshot:** ``` Get a snapshot of NVDA including latest quote, trade, and daily bar ``` **Option chain:** ``` Show me the option chain for SPY expiring in 7 days ``` ### Watchlists ``` Create a watchlist called "Tech Stocks" with AAPL, MSFT, GOOGL ``` ``` Show me all my watchlists ``` ``` Add TSLA to my "Tech Stocks" watchlist ``` ## Programmatic Usage (Python SDK) While the MCP server is designed for natural language use, you can also use the Alpaca Python SDK directly: ```python from alpaca.trading.client import TradingClient from alpaca.trading.requests import MarketOrderRequest from alpaca.trading.enums import OrderSide, TimeInForce import os # Initialize client client = TradingClient( api_key=os.environ["ALPACA_API_KEY"], secret_key=os.environ["ALPACA_SECRET_KEY"], paper=True # Use paper trading ) # Get account info account = client.get_account() print(f"Buying power: ${account.buying_power}") # Place market order order_data = MarketOrderRequest( symbol="AAPL", qty=10, side=OrderSide.BUY, time_in_force=TimeInForce.DAY ) order = client.submit_order(order_data) print(f"Order submitted: {order.id}") # Get all positions positions = client.get_all_positions() for position in positions: print(f"{position.symbol}: {position.qty} shares @ ${position.avg_entry_price}") # Cancel all orders client.cancel_orders() ``` For market data: ```python from alpaca.data.historical import StockHistoricalDataClient from alpaca.data.requests import StockBarsRequest from alpaca.data.timeframe import TimeFrame from datetime import datetime, timedelta # Initialize data client (no auth needed for free data) data_client = StockHistoricalDataClient( api_key=os.environ["ALPACA_API_KEY"], secret_key=os.environ["ALPACA_SECRET_KEY"] ) # Get historical bars request_params = StockBarsRequest( symbol_or_symbols=["AAPL", "TSLA"], timeframe=TimeFrame.Day, start=datetime.now() - timedelta(days=30), end=datetime.now() ) bars = data_client.get_stock_bars(request_params) for symbol, bar_set in bars.items(): print(f"\n{symbol}:") for bar in bar_set: print(f" {bar.timestamp}: O=${bar.open} H=${bar.high} L=${bar.low} C=${bar.close}") ``` ## Example Prompts ### Account & Portfolio - "What's my current portfolio value?" - "Show me my trading activity from yesterday" - "What's my day trade count?" ### Orders - "Cancel all my pending orders" - "Show me all open orders for AAPL" - "Replace my TSLA order with a new limit price of $245" ### Positions - "What positions do I currently hold?" - "Close my entire NVDA position" - "What's my average entry price for MSFT?" ### Market Data - "Get the latest trade for BTC/USD" - "Show me hourly bars for SPY from last week" - "What's the bid-ask spread for AAPL?" ### Options - "Show me put options for QQQ with delta around -0.30" - "Get Greeks for SPY call option with strike 450 expiring next Friday" - "What are the latest option trade prices for AAPL?" ### Watchlists - "Delete my 'Old Stocks' watchlist" - "Remove TSLA from my 'Tech' watchlist" - "Update my watchlist to include COIN" ## Troubleshooting ### Tools not appearing in MCP client 1. **Restart your MCP client** after updating config 2. **Start a fresh chat/session** to clear cached tool lists 3. **Verify config syntax** — JSON must be valid (use a JSON validator) 4. **Check logs** — Claude Desktop: View → Developer → Server Logs 5. **Test uvx** — Run `uvx alpaca-mcp-server --help` in terminal to verify installation ### Authentication errors ``` Error: Invalid API credentials ``` **Solution:** - Verify `ALPACA_API_KEY` and `ALPACA_SECRET_KEY` are set correctly - Ensure no extra quotes or whitespace in env vars - Check if using paper keys with `ALPACA_PAPER_TRADE=true` or live keys with `false` - Regenerate keys in Alpaca dashboard if needed ### Live trading not working ``` Error: This endpoint is not available for paper trading ``` **Solution:** - Set `ALPACA_PAPER_TRADE=false` in env vars - Use live trading API keys (not paper keys) - Restart MCP client after changing config ### Specific tools not available If certain tools are missing (e.g., options tools): **Solution:** - Remove or update `ALPACA_TOOLSETS` to include the toolset you need - Default is all toolsets — if you've filtered, add back missing ones: ```json { "env": { "ALPACA_TOOLSETS": "account,trading,stock-data,options-data" } } ``` ### Order placement fails ``` Error: Insufficient buying power ``` **Solution:** - Check account balance with "What's my buying power?" - Reduce order quantity - In paper trading, you have $100k virtual cash by default ``` Error: Symbol not found ``` **Solution:** - Verify symbol is correct (e.g., "AAPL" not "APPLE") - Check if asset is tradable: "Is AAPL tradable?" - Some assets may not be available in paper trading ### Rate limiting ``` Error: Rate limit exceeded ``` **Solution:** - Alpaca has rate limits (200 requests/minute for paper, varies for live)