Alpaca MCP Server Trading

Skill by 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 package manager
Alpaca API keys (free paper trading account at alpaca.markets)

Get API Keys

Sign up at Alpaca Dashboard
Create a paper trading account
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):

{
  "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:

{
  "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:

{
  "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

Go to File → Settings → Tools → Model Context Protocol (MCP)
Add new server:
- Type: stdio
- Command: uvx
- Arguments: alpaca-mcp-server

Set environment variables:

ALPACA_API_KEY=your_alpaca_api_key
ALPACA_SECRET_KEY=your_alpaca_secret_key

Docker

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:

{
  "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:

{
  "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:

{
  "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:

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:

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

Restart your MCP client after updating config
Start a fresh chat/session to clear cached tool lists
Verify config syntax — JSON must be valid (use a JSON validator)
Check logs — Claude Desktop: View → Developer → Server Logs
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:

{
  "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)
Add delays between rapid requests
Use batch endpoints where available (e.g., get multiple positions at once)

Upgrading from V1

If you used alpaca-mcp-server V1:

V2 is a complete rewrite — tool names and parameters have changed
Remove old config — Delete any .env files or init commands from V1 setup
Update MCP client config — Use the V2 config format shown above
Clear caches — Restart MCP client and start fresh sessions
Update prompts — Remove references to V1-specific tool names
To stay on V1: Pin to uvx alpaca-mcp-server==1.x.x serve in config

Docker issues

Error: Cannot connect to Docker daemon

Solution:

Ensure Docker is running
On macOS/Windows: Start Docker Desktop
Test with docker ps

Testing

The MCP server exposes tools dynamically — test by asking your AI assistant:

List all available Alpaca tools

Or verify directly with the MCP inspector (if your client supports it).

For paper trading, you can freely test all operations without risk. Recommended test flow:

"What's my account balance?"
"Buy 1 share of AAPL at market price"
"Show my current positions"
"Get a quote for AAPL"
"Cancel all orders"
"Close my AAPL position"

Resources

Disclosure

This is a trading platform. Use paper trading for testing. Live trading involves real money and risk of loss. Past performance does not guarantee future results. Alpaca Securities LLC is a member of FINRA/SIPC. See alpaca.markets/disclosures for important disclosures.

alpaca-mcp-server-trading

Alpaca MCP Server Trading

Overview

Installation

Prerequisites

Get API Keys

Configuration by MCP Client

Claude Desktop

Cursor

VS Code

PyCharm

Docker

Configuration

Switching to Live Trading

Toolset Filtering

Common Usage Patterns

Getting Account Information

Trading Stocks

Trading Crypto

Trading Options

Market Data

Watchlists

Programmatic Usage (Python SDK)

Example Prompts

Account & Portfolio

Orders

Positions

Market Data

Options

Watchlists

Troubleshooting

Tools not appearing in MCP client

Authentication errors

Live trading not working

Specific tools not available

Order placement fails

Rate limiting

Upgrading from V1

Docker issues

Testing

Resources

Disclosure