Skillget

alpaca-mcp-server

mcp
SUMMARY

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

README.md

Alpaca logo

X
Reddit
Slack
LinkedIn
Forum
Docs
Python SDK

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.

Alpaca MCP Server v2 is here. This version is a complete rewrite built with FastMCP and OpenAPI. If you're upgrading from v1, please read the Upgrade Guide — tool names, parameters, and configuration have changed.

Table of Contents

Upgrading from V1

V2 is a complete rewrite built with FastMCP and OpenAPI. None of the V1 tools exist in V2 — tool names, parameters, and schemas have changed. You cannot use V2 as a drop-in replacement if your setup depends on specific V1 tool names or parameters.

What changes

Aspect V1 V2
Tool names Hand-crafted (e.g. get_account_info) Spec-derived with overrides (e.g. get_account_info — names may overlap but schemas differ)
Parameters Custom schemas Aligned with Alpaca API specs
Configuration .env + init command Env vars in MCP client config only
Tool filtering Not supported ALPACA_TOOLSETS env var
Whitelisting Not supported Use ALPACA_TOOLSETS to restrict tools

How to avoid V1-style usage in V2

MCP clients discover tools dynamically from the server. There is no config file where you "whitelist" tool names — the client gets whatever tools the server exposes. To avoid your client or AI assistant using V2 incorrectly:

  1. Do not reuse V1 config — Treat V2 as a new server. Update your MCP client config with the new command/args; remove any .env or init-based setup.
  2. Clear tool caches — Restart your MCP client (Claude Desktop, Cursor, VS Code, etc.) after switching so it fetches the new tool list instead of using a stale one.
  3. Start a fresh chat/session — Existing conversations may have cached references to old tool names. Start a new chat so the LLM sees the current V2 tools and their schemas.
  4. Update custom instructions and rules — If you have Cursor rules, Claude instructions, or other prompts that mention specific V1 tool names (e.g. "use get_account_info"), update them to match V2 tool names or remove those references and let the LLM discover tools from context.
  5. Restrict tools with ALPACA_TOOLSETS — If you previously limited which capabilities your assistant could use, V2 supports server-side filtering via the ALPACA_TOOLSETS env var. See Configuration > Toolset Filtering for the list of toolsets.

Summary

Assume no backward compatibility with V1. Reconfigure your MCP client for V2, restart it, and use a fresh session. Check the Available Tools section for the current tool list.

If you had custom V1 workflows

If you documented allowed tools, wrote scripts that call tools by name, or built prompts around specific V1 tool/parameter shapes — treat them as obsolete. Recreate them using the Available Tools listed below and the current parameter schemas exposed by the server.

Staying on V1

If you need to stay on V1, pin to the last V1 release (e.g. uvx alpaca-mcp-server==1.x.x serve) in your MCP client config. V1 remains available on PyPI for existing setups.

Prerequisites

Getting Your API Keys

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

Setup

Add the server to your MCP client config, then restart the client. No init command, no .env files — credentials are set in one place only.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) 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"
      }
    }
  }
}

Cursor

Install from the Cursor Directory in a few clicks, or 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"
      }
    }
  }
}

VS Code

Create .vscode/mcp.json in your project root. See the official docs.

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

PyCharm

See the official guide.

  1. Go to File → Settings → Tools → Model Context Protocol (MCP)
  2. Add a new server:
  • Type: stdio
  • Command: uvx
  • Arguments: alpaca-mcp-server
  1. Set environment variables:
 ALPACA_API_KEY=your_alpaca_api_key
 ALPACA_SECRET_KEY=your_alpaca_secret_key

Claude Code 

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

Verify with /mcp in the Claude Code CLI.

Gemini CLI

See the Gemini CLI MCP docs.

Add to your settings.json:

{
  "mcpServers": {
    "alpaca": {
      "type": "stdio",
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "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 your MCP client config:

{
  "mcpServers": {
    "alpaca": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ALPACA_API_KEY=your_key",
        "-e", "ALPACA_SECRET_KEY=your_secret",
        "-e", "ALPACA_PAPER_TRADE=true",
        "mcp/alpaca:latest"
      ]
    }
  }
}

Configuration

All configuration is through environment variables set in your MCP client config. No files are written to disk.

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 list of toolsets to enable

Switching to Live Trading

Update the env block in your MCP client config and restart:

{
  "env": {
    "ALPACA_API_KEY": "your_live_api_key",
    "ALPACA_SECRET_KEY": "your_live_secret_key",
    "ALPACA_PAPER_TRADE": "false"
  }
}

Toolset Filtering

By default, all tools are enabled. To limit the server to specific toolsets, set ALPACA_TOOLSETS:

{
  "env": {
    "ALPACA_API_KEY": "...",
    "ALPACA_SECRET_KEY": "...",
    "ALPACA_TOOLSETS": "stock-data,crypto-data"
  }
}

Available toolsets:

Toolset Description
account Account info, config, portfolio history, activities
trading Orders, positions, exercise options
watchlists Watchlist CRUD operations
assets Asset lookup, option contracts, calendar, clock
stock-data Stock bars, quotes, trades, snapshots, screeners
crypto-data Crypto bars, quotes, trades, snapshots, orderbooks
options-data Option bars, quotes, trades, snapshots, chain, exchange codes
corporate-actions Corporate action announcements

Features

  • Market Data — Real-time quotes, trades, and price bars for stocks, crypto, and options. Historical data with flexible timeframes. Option Greeks and implied volatility.
  • Account Management — View balances, buying power, account status, and portfolio history.
  • Order Management — Place market, limit, stop, stop-limit, and trailing-stop orders for stocks, crypto, and options. Cancel orders individually or in bulk.
  • Options Trading — Search contracts by expiration/strike/type. Place single-leg or multi-leg strategies. Get latest quotes, Greeks, and IV.
  • Crypto Trading — Market, limit, and stop-limit orders with GTC/IOC. Quantity or notional-based.
  • Position Management — View, close, or liquidate positions. Exercise option contracts.
  • Market Status — Market open/close times, calendar, corporate actions.
  • Watchlists — Create, update, and manage watchlists.
  • Asset Search — Query details for stocks, ETFs, crypto, and options with filtering.

Example Prompts

Basic Trading

  1. What's my current account balance and buying power on Alpaca?
  2. Show me my current positions in my Alpaca account.
  3. Buy 5 shares of AAPL at market price.
  4. Sell 5 shares of TSLA with a limit price of $300.
  5. Cancel all open stock orders.
  6. Cancel the order with ID abc123.
  7. Liquidate my entire position in GOOGL.
  8. Close 10% of my position in NVDA.
  9. Place a limit order to buy 100 shares of MSFT at $450.
  10. Place a market order to sell 25 shares of META.

Crypto Trading

  1. Place a market order to buy 0.01 ETH/USD.
  2. Place a limit order to sell 0.01 BTC/USD at $110,000.

Option Trading

  1. Show me available option contracts for AAPL expiring next month.
  2. Get the latest quote for the AAPL250613C00200000 option.
  3. Retrieve the option snapshot for the SPY250627P00400000 option.
  4. Liquidate my position in 2 contracts of QQQ calls expiring next week.
  5. Place a market order to buy 1 call option on AAPL expiring next Friday.
  6. What are the option Greeks for the TSLA250620P00500000 option?
  7. Find TSLA option contracts with strike prices within 5% of the current market price.
  8. Get SPY call options expiring the week of June 16th, 2025, within 10% of market price.
  9. Place a bull call spread using AAPL June 6th options: one with a 190.00 strike and the other with a 200.00 strike.
  10. Exercise my NVDA call option contract NVDA250919C001680.

Market Information

To access the latest 15-minute data, you need to subscribe to the Algo Trader Plus Plan.

  1. What are the market open and close times today?
  2. Show me the market calendar for next week.
  3. Show me recent cash dividends and stock splits for AAPL, MSFT, and GOOGL in the last 3 months.
  4. Get all corporate actions for SPY including dividends, splits, and any mergers in the past year.
  5. What are the upcoming corporate actions scheduled for SPY in the next 6 months?

Historical & Real-time Data

  1. Show me AAPL's daily price history for the last 5 trading days.
  2. What was the closing price of TSLA yesterday?
  3. Get the latest bar for GOOGL.
  4. What was the latest trade price for NVDA?
  5. Show me the most recent quote for MSFT.
  6. Retrieve the last 100 trades for AMD.
  7. Show me 1-minute bars for AMZN from the last 2 hours.
  8. Get 5-minute intraday bars for TSLA from last Tuesday through last Friday.
  9. Get a comprehensive stock snapshot for AAPL showing latest quote, trade, minute bar, daily bar, and previous daily bar all in one view.
  10. Compare market snapshots for TSLA, NVDA, and MSFT to analyze their current bid/ask spreads, latest trade prices, and daily performance.

Orders

  1. Show me all my open and filled orders from this week.
  2. What orders do I have for AAPL?
  3. List all limit orders I placed in the past 3 days.
  4. Filter all orders by status: filled.
  5. Get me the order history for yesterday.

Watchlists

At this moment, you can only view and update trading watchlists created via Alpaca's Trading API through the API itself

  1. Create a new watchlist called "Tech Stocks" with AAPL, MSFT, and NVDA.
  2. Update my "Tech Stocks" watchlist to include TSLA and AMZN.
  3. What stocks are in my "Dividend Picks" watchlist?
  4. Remove META from my "Growth Portfolio" watchlist.
  5. List all my existing watchlists.

Asset Information

  1. Search for details about the asset 'AAPL'.
  2. Show me the top 5 tradable crypto assets by trading volume.
  3. Get all NASDAQ active US equity assets and filter the results to show only tradable securities

Combined Scenarios

  1. Get today's market clock and show me my buying power before placing a limit buy order for TSLA at $340.
  2. Place a bull call spread with SPY July 3rd options: sell one 5% above and buy one 3% below the current SPY price.

Available Tools

Account & Portfolio

  • get_account_info — Balance, margin, and account status
  • get_account_config — Trading restrictions, margin settings, PDT checks
  • update_account_config — Update account configuration settings
  • get_portfolio_history — Equity and P/L over time
  • get_account_activities — Fills, dividends, transfers
  • get_account_activities_by_type — Activities filtered by type

Trading (Orders)

  • get_orders — Retrieve orders with filters
  • get_order_by_id — Single order by ID
  • get_order_by_client_id — Single order by client order ID
  • replace_order_by_id — Replace an existing open order
  • cancel_order_by_id — Cancel a specific order
  • cancel_all_orders — Cancel all open orders
  • place_stock_order — Stocks/ETFs (market, limit, stop, stop-limit, trailing-stop, brackets)
  • place_crypto_order — Crypto (market, limit, stop-limit)
  • place_option_order — Options (single-leg or multi-leg)

Positions

  • get_all_positions — All current positions
  • get_open_position — Details for a specific position
  • close_position — Close a specific position
  • close_all_positions — Liquidate entire portfolio
  • exercise_options_position — Exercise a held option contract
  • do_not_exercise_options_position — Do-not-exercise instruction

Watchlists

  • create_watchlist — Create a new watchlist
  • get_watchlists — List all watchlists
  • get_watchlist_by_id — Get a specific watchlist
  • update_watchlist_by_id — Update a watchlist
  • delete_watchlist_by_id — Delete a watchlist
  • add_asset_to_watchlist_by_id — Add an asset to a watchlist
  • remove_asset_from_watchlist_by_id — Remove an asset from a watchlist

Assets & Market Info

  • get_all_assets — List assets with optional filtering
  • get_asset — Detailed info for a specific asset
  • get_option_contracts — Option contracts for underlying symbol(s)
  • get_option_contract — Single option contract by symbol or ID
  • get_calendar — Market calendar for a date range
  • get_clock — Current market status and next open/close
  • get_corporate_action_announcements — Corporate action announcements
  • get_corporate_action_announcement — Single announcement by ID

Stock Data

  • get_stock_bars — Historical OHLCV bars
  • get_stock_quotes — Historical bid/ask quotes
  • get_stock_trades — Historical trades
  • get_stock_latest_bar — Latest minute bar
  • get_stock_latest_quote — Latest quote
  • get_stock_latest_trade — Latest trade
  • get_stock_snapshot — Comprehensive snapshot
  • get_most_active_stocks — Most active by volume/trade count
  • get_market_movers — Top gainers and losers

Crypto Data

  • get_crypto_bars — Historical OHLCV bars
  • get_crypto_quotes — Historical quotes
  • get_crypto_trades — Historical trades
  • get_crypto_latest_bar — Latest minute bar
  • get_crypto_latest_quote — Latest quote
  • get_crypto_latest_trade — Latest trade
  • get_crypto_snapshot — Comprehensive snapshot
  • get_crypto_latest_orderbook — Latest orderbook

Options Data

  • get_option_bars — Historical OHLCV bars
  • get_option_trades — Historical trades
  • get_option_latest_trade — Latest trade
  • get_option_latest_quote — Latest quote with bid/ask and exchange info
  • get_option_snapshot — Snapshot with Greeks and IV
  • get_option_chain — Full option chain for an underlying
  • get_option_exchange_codes — Exchange code to name mapping

Corporate Actions

  • get_corporate_actions — Corporate action announcements from market data

Testing

The project includes a multi-layered test suite that runs in CI on every pull request:

  • Integrity tests — Validate consistency between OpenAPI specs, toolset definitions, and tool name/description overrides. No network or credentials required.
  • Server construction tests — Build the server with mocked credentials and verify the correct number of tools are exposed. No network required.
  • Paper API integration tests — Execute real calls against the Alpaca paper trading API, covering account info, market data, order lifecycle, watchlists, positions, and more. Requires ALPACA_API_KEY and ALPACA_SECRET_KEY.

Run the full suite locally:

# Core tests (no credentials needed)
pytest tests/test_integrity.py tests/test_server_construction.py -v

# Integration tests (requires paper API keys)
ALPACA_API_KEY=... ALPACA_SECRET_KEY=... pytest tests/ -m integration -v

Project Structure

alpaca-mcp-server/
├── src/
│   └── alpaca_mcp_server/
│       ├── __init__.py
│       ├── cli.py            ← CLI entry point
│       ├── server.py         ← FastMCP server built from OpenAPI specs
│       ├── names.py          ← Tool name and description overrides
│       ├── toolsets.py       ← Toolset → operationId allowlists
│       ├── overrides.py      ← Hand-crafted tools for complex trading endpoints
│       ├── market_data_overrides.py ← Hand-crafted tools for historical data
│       └── specs/
│           ├── trading-api.json
│           └── market-data-api.json
├── tests/
│   ├── conftest.py           ← Shared fixtures and paper-account cleanup
│   ├── test_integrity.py     ← Spec ↔ toolset ↔ names consistency checks
│   ├── test_server_construction.py ← Server build verification
│   └── test_paper_integration.py   ← Paper API integration tests
├── scripts/
│   └── sync-specs.sh        ← Download latest OpenAPI specs
├── .github/
│   └── workflows/
│       └── ci.yml            ← CI pipeline (core + integration)
├── AGENTS.md                 ← Instructions for coding agents
├── pyproject.toml
└── README.md

Troubleshooting

  • uv/uvx not found: Install uv from the official guide (https://docs.astral.sh/uv/getting-started/installation/) and then restart your terminal so uv/uvx are on PATH.
  • Credentials missing: Set ALPACA_API_KEY and ALPACA_SECRET_KEY in the client's env block. Paper mode default is ALPACA_PAPER_TRADE = True.
  • Client didn't pick up new config: Restart the client (Cursor, Claude Desktop, VS Code) after changes.
  • HTTP port conflicts: If using --transport streamable-http, change --port to a free port.

Disclosure

Insights generated by our MCP server and connected AI agents are for educational and informational purposes only and should not be taken as investment advice. Alpaca does not recommend any specific securities or investment strategies.Please conduct your own due diligence before making any decisions. All firms mentioned operate independently and are not liable for one another.

Options trading is not suitable for all investors due to its inherent high risk, which can potentially result in significant losses. Please read Characteristics and Risks of Standardized Options (Options Disclosure Document) before investing in options.

Alpaca does not prepare, edit, endorse, or approve Third Party Content. Alpaca does not guarantee the accuracy, timeliness, completeness or usefulness of Third Party Content, and is not responsible or liable for any content, advertising, products, or other materials on or available from third party sites.

All investments involve risk, and the past performance of a security, or financial product does not guarantee future results or returns. There is no guarantee that any investment strategy will achieve its objectives. Please note that diversification does not ensure a profit, or protect against loss. There is always the potential of losing money when you invest in securities, or other financial products. Investors should consider their investment objectives and risks carefully before investing.

The algorithm's calculations are based on historical and real-time market data but may not account for all market factors, including sudden price moves, liquidity constraints, or execution delays. Model assumptions, such as volatility estimates and dividend treatments, can impact performance and accuracy. Trades generated by the algorithm are subject to brokerage execution processes, market liquidity, order priority, and timing delays. These factors may cause deviations from expected trade execution prices or times. Users are responsible for monitoring algorithmic activity and understanding the risks involved. Alpaca is not liable for any losses incurred through the use of this system.

Past hypothetical backtest results do not guarantee future returns, and actual results may vary from the analysis.

The Paper Trading API is offered by AlpacaDB, Inc. and does not require real money or permit a user to transact in real securities in the market. Providing use of the Paper Trading API is not an offer or solicitation to buy or sell securities, securities derivative or futures products of any kind, or any type of trading or investment advice, recommendation or strategy, given or in any manner endorsed by AlpacaDB, Inc. or any AlpacaDB, Inc. affiliate and the information made available through the Paper Trading API is not an offer or solicitation of any kind in any jurisdiction where AlpacaDB, Inc. or any AlpacaDB, Inc. affiliate (collectively, "Alpaca") is not authorized to do business.

Securities brokerage services are provided by Alpaca Securities LLC ("Alpaca Securities"), member FINRA/SIPC, a wholly-owned subsidiary of AlpacaDB, Inc. Technology and services are offered by AlpacaDB, Inc.

Cryptocurrency services are provided by Alpaca Crypto LLC ("Alpaca Crypto"), a FinCEN registered money services business (NMLS # 2160858), and a wholly-owned subsidiary of AlpacaDB, Inc. Alpaca Crypto is not a member of SIPC or FINRA. Cryptocurrencies are not stocks and your cryptocurrency investments are not protected by either FDIC or SIPC. Cryptocurrency assets are highly volatile and speculative, involving substantial risk of loss, and are not insured by the FDIC or any government agency. Customers should be aware of the various risks prior to engaging these services, including potential loss of principal, cybersecurity considerations, regulatory developments, and the evolving nature of digital asset technology. For additional information on the risks of cryptocurrency, please click here.

This is not an offer, solicitation of an offer, or advice to buy or sell securities or cryptocurrencies or open a brokerage account or cryptocurrency account in any jurisdiction where Alpaca Securities or Alpaca Crypto, respectively, are not registered or licensed, as applicable.

Privacy Policy

For information about how Alpaca handles your data, please review:

Data Collection

  • What is collected: User agent string ('ALPACA-MCP-SERVER') for API calls
  • How it's used: To identify MCP server usage and improve user experience
  • Third-party sharing: Not shared with third parties
  • Retention: Retained per Alpaca's standard data retention policy
  • Opt-out: Modify the 'USER_AGENT' constant in '.github/core/user_agent_mixin.py' or remove 'UserAgentMixin' from client class definitions

Security Notice

This server can place real trades and access your portfolio. Treat your API keys as sensitive credentials. Review all actions proposed by the LLM carefully, especially for complex options strategies or multi-leg trades.

HTTP Transport Security: When using HTTP transport, the server defaults to localhost (127.0.0.1:8000) for security. For remote access, you can bind to all interfaces with --host 0.0.0.0, use SSH tunneling (ssh -L 8000:localhost:8000 user@server), or set up a reverse proxy with authentication for secure access.

Support

For issues or questions, please contact us at [email protected].

GitHub Issues: https://github.com/alpacahq/alpaca-mcp-server/issues
GitHub Pull requests: https://github.com/alpacahq/alpaca-mcp-server/pulls

MCP Registry Metadata

mcp-name: io.github.alpacahq/alpaca-mcp-server

Reviews (0)

No results found