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:
- 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.
- 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.
- 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.
- 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.
- 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
- Visit the Alpaca Dashboard
- Create a free paper trading account
- Generate API keys from the dashboard
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 |
news | News articles for stocks and crypto |
fixed-income-data | Fixed income (bond/treasury) quotes |
locates | Short-sale locate requests and quotes |
ReadMe Docs MCP
Docs are scoped to the Trading API, Market Data API, and Authentication API specs; Broker API endpoint docs are intentionally excluded from this server.
If the ReadMe MCP lookup fails, tool responses include fallback links to Alpaca's public docs plus llms.txt and llms-full.txt.
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.
- News — News articles filterable by ticker and date range.
- 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
- What's my current account balance and buying power on Alpaca?
- Show me my current positions in my Alpaca account.
- Buy 5 shares of AAPL at market price.
- Sell 5 shares of TSLA with a limit price of $300.
- Cancel all open stock orders.
- Cancel the order with ID abc123.
- Liquidate my entire position in GOOGL.
- Close 10% of my position in NVDA.
- Place a limit order to buy 100 shares of MSFT at $450.
- Place a market order to sell 25 shares of META.
Crypto Trading
- Place a market order to buy 0.01 ETH/USD.
- Place a limit order to sell 0.01 BTC/USD at $110,000.
Option Trading
- Show me available option contracts for AAPL expiring next month.
- Get the latest quote for the AAPL250613C00200000 option.
- Retrieve the option snapshot for the SPY250627P00400000 option.
- Liquidate my position in 2 contracts of QQQ calls expiring next week.
- Place a market order to buy 1 call option on AAPL expiring next Friday.
- What are the option Greeks for the TSLA250620P00500000 option?
- Find TSLA option contracts with strike prices within 5% of the current market price.
- Get SPY call options expiring the week of June 16th, 2025, within 10% of market price.
- Place a bull call spread using AAPL June 6th options: one with a 190.00 strike and the other with a 200.00 strike.
- 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.
- What are the market open and close times today?
- Show me the market calendar for next week.
- Show me recent cash dividends and stock splits for AAPL, MSFT, and GOOGL in the last 3 months.
- Get all corporate actions for SPY including dividends, splits, and any mergers in the past year.
- What are the upcoming corporate actions scheduled for SPY in the next 6 months?
Historical & Real-time Data
- Show me AAPL's daily price history for the last 5 trading days.
- What was the closing price of TSLA yesterday?
- Get the latest bar for GOOGL.
- What was the latest trade price for NVDA?
- Show me the most recent quote for MSFT.
- Retrieve the last 100 trades for AMD.
- Show me 1-minute bars for AMZN from the last 2 hours.
- Get 5-minute intraday bars for TSLA from last Tuesday through last Friday.
- Get a comprehensive stock snapshot for AAPL showing latest quote, trade, minute bar, daily bar, and previous daily bar all in one view.
- Compare market snapshots for TSLA, NVDA, and MSFT to analyze their current bid/ask spreads, latest trade prices, and daily performance.
Orders
- Show me all my open and filled orders from this week.
- What orders do I have for AAPL?
- List all limit orders I placed in the past 3 days.
- Filter all orders by status: filled.
- 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
- Create a new watchlist called "Tech Stocks" with AAPL, MSFT, and NVDA.
- Update my "Tech Stocks" watchlist to include TSLA and AMZN.
- What stocks are in my "Dividend Picks" watchlist?
- Remove META from my "Growth Portfolio" watchlist.
- List all my existing watchlists.
Asset Information
- Search for details about the asset 'AAPL'.
- Show me the top 5 tradable crypto assets by trading volume.
- Get all NASDAQ active US equity assets and filter the results to show only tradable securities
Combined Scenarios
- Get today's market clock and show me my buying power before placing a limit buy order for TSLA at $340.
- 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 statusget_account_config — Trading restrictions, margin settings, PDT checksupdate_account_config — Update account configuration settingsget_portfolio_history — Equity and P/L over timeget_account_activities — Fills, dividends, transfersget_account_activities_by_type — Activities filtered by type
Trading (Orders)
get_orders — Retrieve orders with filtersget_order_by_id — Single order by IDget_order_by_client_id — Single order by client order IDreplace_order_by_id — Replace an existing open ordercancel_order_by_id — Cancel a specific ordercancel_all_orders — Cancel all open ordersplace_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 positionsget_open_position — Details for a specific positionclose_position — Close a specific positionclose_all_positions — Liquidate entire portfolioexercise_options_position — Exercise a held option contractdo_not_exercise_options_position — Do-not-exercise instruction
Watchlists
create_watchlist — Create a new watchlistget_watchlists — List all watchlistsget_watchlist_by_id — Get a specific watchlistupdate_watchlist_by_id — Update a watchlistdelete_watchlist_by_id — Delete a watchlistadd_asset_to_watchlist_by_id — Add an asset to a watchlistremove_asset_from_watchlist_by_id — Remove an asset from a watchlist
Assets & Market Info
get_all_assets — List assets with optional filteringget_asset — Detailed info for a specific assetget_option_contracts — Option contracts for underlying symbol(s)get_option_contract — Single option contract by symbol or IDget_calendar — Market calendar for a date rangeget_clock — Current market status and next open/closeget_corporate_action_announcements — Corporate action announcementsget_corporate_action_announcement — Single announcement by ID
Stock Data
get_stock_bars — Historical OHLCV barsget_stock_quotes — Historical bid/ask quotesget_stock_trades — Historical tradesget_stock_latest_bar — Latest minute barget_stock_latest_quote — Latest quoteget_stock_latest_trade — Latest tradeget_stock_snapshot — Comprehensive snapshotget_most_active_stocks — Most active by volume/trade countget_market_movers — Top gainers and losers
Crypto Data
get_crypto_bars — Historical OHLCV barsget_crypto_quotes — Historical quotesget_crypto_trades — Historical tradesget_crypto_latest_bar — Latest minute barget_crypto_latest_quote — Latest quoteget_crypto_latest_trade — Latest tradeget_crypto_snapshot — Comprehensive snapshotget_crypto_latest_orderbook — Latest orderbook
Options Data
get_option_bars — Historical OHLCV barsget_option_trades — Historical tradesget_option_latest_trade — Latest tradeget_option_latest_quote — Latest quote with bid/ask and exchange infoget_option_snapshot — Snapshot with Greeks and IVget_option_chain — Full option chain for an underlyingget_option_exchange_codes — Exchange code to name mapping
Corporate Actions
get_corporate_actions — Corporate action announcements from market data
News
get_news — News articles for stocks and crypto
Fixed Income Data
get_fixed_income_latest_quotes — Latest quotes for fixed income securities by ISIN
Locates (Short Selling) — not available in paper trading
get_locates — List locate requests filtered by status, symbol, or date rangecreate_locate — Create a locate request for a short saleget_locate — Get a single locate request by IDget_locate_quotes — Get locate availability and pricing for symbols
Documentation
search_alpaca_docs — Search Alpaca documentation pages and guidesfetch_alpaca_doc — Fetch one Alpaca ReadMe documentation page by page IDsearch_alpaca_api_specs — Search Alpaca API reference endpoints by topic, path, parameter, or schema termlist_alpaca_api_endpoints — List endpoints for one allowed Alpaca OpenAPI specget_alpaca_endpoint_docs — Fetch reference docs for one exact Alpaca API endpoint by method and path
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.
- ReadMe integration tests — Execute live documentation lookup calls against Alpaca's ReadMe MCP. Requires
ALPACA_RUN_README_INTEGRATION=true when run locally.
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
# ReadMe docs integration tests (requires network, no Alpaca credentials)
ALPACA_RUN_README_INTEGRATION=true pytest tests/test_readme_integration.py -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
│ ├── tool_registry.py ← Tool names, descriptions, and output risk classifications
│ ├── toolsets.py ← Toolset → operationId allowlists
│ ├── overrides.py ← Hand-crafted tools for complex trading endpoints
│ ├── market_data_overrides.py ← Hand-crafted tools for historical data
│ ├── readme_docs.py ← Read-only proxy tools for Alpaca ReadMe docs
│ └── 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_readme_integration.py ← Live ReadMe docs MCP integration tests
│ └── test_paper_integration.py ← Paper API integration tests
├── scripts/
│ └── sync-specs.sh ← Download latest OpenAPI specs
├── .github/
│ └── workflows/
│ ├── ci.yml ← CI pipeline (core + integration)
│ └── publish-pypi.yml ← PyPI publish on GitHub Release
├── 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 (
APCA-MCP-TRADING/<version>) 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: Set the
ALPACA_MCP_USER_AGENT environment variable to an empty string; no User-Agent header will be sent
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: Streamable HTTP defaults to localhost (127.0.0.1:8000) and validates Host and Origin headers. Docker defaults to stdio. Helm defaults to ClusterIP HTTP with ingress off. Binding to 0.0.0.0 does not provide authentication. This package does not configure MCP OAuth, so do not expose it directly to the public internet. Operators that provide standards-based MCP authentication must also set FastMCP's FASTMCP_HTTP_ALLOWED_HOSTS to the exact public hostnames.
Support
For issues or questions, please contact us at support@alpaca.markets.
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