Alpaca's MCP server lets you trade stocks and options, analyze market data, and build strategies through Alpaca's Trading API
This is a Model Context Protocol (MCP) server implementation for Alpaca's Trading API. It enables large language models (LLMs) on Claude Desktop, Cursor, or VScode to interact with Alpaca's trading infrastructure using natural language (English). This server supports stock trading, options trading, portfolio management, watchlist handling, and real-time market data access.
Clone the repository and navigate to the directory:
git clone https://github.com/alpacahq/alpaca-mcp-server.git
cd alpaca-mcp-server
Create and activate a virtual environment and Install the required packages:
Option A: Using pip (traditional)
python3 -m venv myvenv
source myvenv/bin/activate # On Windows: myvenv\Scripts\activate
pip install -r requirements.txt
Option B: Using uv (modern, faster)
To use uv, you'll first need to install it. See the official uv installation guide for detailed installation instructions for your platform.
uv venv myvenv
source myvenv/bin/activate # On Windows: myvenv\Scripts\activate
uv pip install -r requirements.txt
Note: The virtual environment will use the Python version that was used to create it. If you run the command with Python 3.10 or newer, your virtual environment will also use Python 3.10+. If you want to confirm the version, you can run python3 --version
after activating the virtual environment.
After cloning and activating the virtual environment, your directory structure should look like this:
alpaca-mcp-server/ β This is the workspace folder (= project root)
βββ alpaca_mcp_server.py β Script is directly in workspace root
βββ .github/ β VS Code settings (for VS Code users)
β βββ core/ β Core utility modules
β βββ workflows/ β GitHub Actions workflows
βββ .vscode/ β VS Code settings (for VS Code users)
β βββ mcp.json
βββ venv/ β Virtual environment folder
β βββ bin/python
βββ .env.example β Environment template (use this to create `.env` file)
βββ .gitignore
βββ Dockerfile β Docker configuration (for Docker use)
βββ .dockerignore β Docker ignore (for Docker use)
βββ requirements.txt
βββ README.md
Copy the example environment file in the project root by running this command:
cp .env.example .env
Replace the credentials (e.g. API keys) in the .env
file:
ALPACA_API_KEY = "your_alpaca_api_key_for_paper_account"
ALPACA_SECRET_KEY = "your_alpaca_secret_key_for_paper_account"
ALPACA_PAPER_TRADE = True
TRADE_API_URL = None
TRDE_API_WSS = None
DATA_API_URL = None
STREAM_DATA_WSS = None
Open a terminal in the project root directory and run the following command:
For local usage (default - stdio transport):
python alpaca_mcp_server.py
For remote usage (HTTP transport):
python alpaca_mcp_server.py --transport http
Available transport options:
--transport stdio
(default): Standard input/output for local client connections--transport http
: HTTP transport for remote client connections (default: 127.0.0.1:8000)--transport sse
: Server-Sent Events transport for remote connections (deprecated)--host HOST
: Host to bind the server to for HTTP/SSE transport (default: 127.0.0.1)--port PORT
: Port to bind the server to for HTTP/SSE transport (default: 8000)Note: For more information about MCP transport methods, see the official MCP transport documentation.
To use Alpaca MCP Server with Claude Desktop, please follow the steps below. The official Claude Desktop setup document is available here: https://modelcontextprotocol.io/quickstart/user
Settings β Developer β Edit Config
claude_desktop_config.json
:Note:
Replace <project_root> with the path to your cloned alpaca-mcp-server directory. This should point to the Python executable inside the virtual environment you created with python3 -m venv venv
in the terminal.
For local usage (stdio transport - recommended):
{
"mcpServers": {
"alpaca": {
"command": "<project_root>/venv/bin/python",
"args": [
"/path/to/alpaca-mcp-server/alpaca_mcp_server.py"
],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key_for_paper_account",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key_for_paper_account"
}
}
}
}
For remote usage (HTTP transport):
{
"mcpServers": {
"alpaca": {
"transport": "http",
"url": "http://your-server-ip:8000/mcp",
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key_for_paper_account",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key_for_paper_account"
}
}
}
}
To use Alpaca MCP Server with Claude Code, please follow the steps below.
The claude mcp add command
is part of Claude Code. If you have the Claude MCP CLI tool installed (e.g. by npm install -g @anthropic-ai/claude-code
), you can use this command to add the server to Claude Code:
claude mcp add alpaca \
/path/to/your/alpaca-mcp-server/venv/bin/python \
/path/to/your/alpaca-mcp-server/alpaca_mcp_server.py \
-e ALPACA_API_KEY=your_api_key \
-e ALPACA_SECRET_KEY=your_secret_key
Note: Replace the paths with your actual project directory paths. This command automatically adds the MCP server configuration to Claude Code without manual JSON editing.
The Claude MCP CLI tool needs to be installed separately. Check following the official pages for availability and installation instructions
To use Alpaca MCP Server with Cursor, please follow the steps below. The official Cursor MCP setup document is available here: https://docs.cursor.com/context/mcp
Prerequisites
Method 1: Using JSON Configuration
Create or edit ~/.cursor/mcp.json
(macOS/Linux) or %USERPROFILE%\.cursor\mcp.json
(Windows):
{
"mcpServers": {
"alpaca": {
"command": "/path/to/your/alpaca-mcp-server/venv/bin/python",
"args": [
"/path/to/your/alpaca-mcp-server/alpaca_mcp_server.py"
],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
Method 2: Using Cursor Settings UI
Note: Replace the paths with your actual project directory paths and API credentials.
To use Alpaca MCP Server with VS Code, please follow the steps below.
VS Code supports MCP servers through GitHub Copilot's agent mode. The official VS Code setup document is available here: https://code.visualstudio.com/docs/copilot/chat/mcp-servers
Prerequisites
Recommendation: Use workspace-specific configuration (.vscode/mcp.json
) instead of user-wide configuration. This allows different projects to use different API keys (multiple paper accounts or live trading) and keeps trading tools isolated from other development work.
For workspace-specific settings:
Create .vscode/mcp.json
in your project root.
Add the Alpaca MCP server configuration manually to the mcp.json file:
For Linux/macOS:
{
"mcp": {
"servers": {
"alpaca": {
"type": "stdio",
"command": "bash",
"args": ["-c", "cd ${workspaceFolder} && source ./venv/bin/activate && python alpaca_mcp_server.py"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
}
For Windows:
{
"mcp": {
"servers": {
"alpaca": {
"type": "stdio",
"command": "cmd",
"args": ["/c", "cd /d ${workspaceFolder} && .\\venv\\Scripts\\activate && python alpaca_mcp_server.py"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
}
Note: Replace ${workspaceFolder}
with your actual project path. For example:
/Users/username/Documents/alpaca-mcp-server
C:\\Users\\username\\Documents\\alpaca-mcp-server
For user-wide settings:
To configure an MCP server for all your workspaces, you can add the server configuration to your user settings.json file. This allows you to reuse the same server configuration across multiple projects.
Specify the server in the mcp
VS Code user settings (settings.json
) to enable the MCP server across all workspaces.
{
"mcp": {
"servers": {
"alpaca": {
"type": "stdio",
"command": "bash",
"args": ["-c", "cd ${workspaceFolder} && source ./venv/bin/activate && python alpaca_mcp_server.py"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
}
To use the Alpaca MCP Server with PyCharm, please follow the steps below. The official setup guide for configuring the MCP Server in PyCharm is available here: https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html
PyCharm supports MCP servers through its integrated MCP client functionality. This configuration ensures proper logging behavior and prevents common startup issues.
Open PyCharm Settings
File β Settings
Tools β Model Context Protocol (MCP)
(or similar location depending on PyCharm version)Add New MCP Server
Add
or +
to create a new server configuration. You can also import the settings from Claude by clicking the corresponding button.Set Environment Variables Add the following environment variables in the Environment Variables parameter:
ALPACA_API_KEY="your_alpaca_api_key"
ALPACA_SECRET_KEY="your_alpaca_secret_key"
MCP_CLIENT=pycharm
To use Alpaca MCP Server with Docker, please follow the steps below.
Prerequisite:
You must have Docker installed on your system.
docker run -it --rm \
-e ALPACA_API_KEY=your_alpaca_api_key \
-e ALPACA_SECRET_KEY=your_alpaca_secret_key \
ghcr.io/chand1012/alpaca-mcp-server:latest
This pulls and runs the latest published version of the server. Replace your_alpaca_api_key
and your_alpaca_secret_key
with your actual keys. If the server exposes a port (e.g., 8080), add -p 8080:8080
to the command.
docker build -t alpaca-mcp-server .
docker run -it --rm \
-e ALPACA_API_KEY=your_alpaca_api_key \
-e ALPACA_SECRET_KEY=your_alpaca_secret_key \
alpaca-mcp-server
Use this if you want to run a modified or development version of the server.
{
"mcpServers": {
"alpaca": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "ALPACA_API_KEY",
"-e", "ALPACA_SECRET_KEY",
"ghcr.io/chand1012/alpaca-mcp-server:latest"
],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
Environment variables can be set either with -e
flags or in the "env"
object, but not both. For Claude Desktop, use the "env"
object.
Security Note: Never share your API keys or commit them to public repositories. Be cautious when passing secrets as environment variables, especially in shared or production environments.
For more advanced Docker usage: See the official Docker documentation.
This MCP server connects to Alpaca's paper trading API by default for safe testing. To enable live trading with real funds, update the following configuration files:
Update environment file in the project directory
Provide your live account keys as environment variables in the .env
file:
ALPACA_API_KEY = "your_alpaca_api_key_for_live_account"
ALPACA_SECRET_KEY = "your_alpaca_secret_key_for_live_account"
ALPACA_PAPER_TRADE = False
TRADE_API_URL = None
TRADE_API_WSS = None
DATA_API_URL = None
STREAM_DATA_WSS = None
Update Configuration file
For example, when using Claude Desktop, provide your live account keys as environment variables in claude_desktop_config.json
:
{
"mcpServers": {
"alpaca": {
"command": "<project_root>/venv/bin/python",
"args": [
"/path/to/alpaca_mcp_server.py"
],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key_for_live_account",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key_for_live_account"
}
}
}
}
get_account_info()
β View balance, margin, and account statusget_positions()
β List all held assetsget_open_position(symbol)
β Detailed info on a specific positionclose_position(symbol, qty|percentage)
β Close part or all of a positionclose_all_positions(cancel_orders)
β Liquidate entire portfolioget_stock_quote(symbol)
β Real-time bid/ask quoteget_stock_bars(symbol, days=5, timeframe="1Day", limit=None, start=None, end=None)
β OHLCV historical bars with flexible timeframes (1Min, 5Min, 1Hour, 1Day, etc.)get_stock_latest_trade(symbol, feed=None, currency=None)
β Latest market trade priceget_stock_latest_bar(symbol, feed=None, currency=None)
β Most recent OHLC barget_stock_snapshot(symbol_or_symbols, feed=None, currency=None)
β Comprehensive snapshot with latest quote, trade, minute bar, daily bar, and previous daily barget_stock_trades(symbol, days=5, limit=None, sort=Sort.ASC, feed=None, currency=None, asof=None)
β Trade-level historyget_orders(status, limit)
β Retrieve all or filtered ordersplace_stock_order(symbol, side, quantity, order_type="market", limit_price=None, stop_price=None, trail_price=None, trail_percent=None, time_in_force="day", extended_hours=False, client_order_id=None)
β Place a stock order of any type (market, limit, stop, stop_limit, trailing_stop)cancel_order_by_id(order_id)
β Cancel a specific ordercancel_all_orders()
β Cancel all open ordersget_option_contracts(underlying_symbol, expiration_date=None, expiration_month=None, expiration_year=None, expiration_week_start=None, strike_price_gte=None, strike_price_lte=None, type=None, status=None, root_symbol=None, limit=None)
β Fetch contracts with comprehensive filtering optionsget_option_latest_quote(option_symbol)
β Latest bid/ask on contractget_option_snapshot(symbol_or_symbols)
β Get Greeks and underlyingplace_option_market_order(legs, order_class=None, quantity=1, time_in_force=TimeInForce.DAY, extended_hours=False)
β Execute option strategyget_market_clock()
β Market open/close scheduleget_market_calendar(start, end)
β Holidays and trading daysget_corporate_announcements(...)
β Historical earnings, dividends, splitscreate_watchlist(name, symbols)
β Create a new listupdate_watchlist(watchlist_id, name=None, symbols=None)
β Modify an existing listget_watchlists()
β Retrieve all saved watchlistsget_asset_info(symbol)
β Search asset metadataget_all_assets(status=None, asset_class=None, exchange=None, attributes=None)
β List all tradable instruments with filtering optionsSee the "Example Queries" section below for 50 real examples covering everything from trading to corporate data to option strategies.
At this moment, you can only view and update trading watchlists created via Alpacaβs Trading API through the API itself
The MCP server provides detailed, well-formatted responses for various trading queries. Here are some examples:
Query: "What are the option Greeks for TSLA250620P00500000?"
Response: Option Details:
Greeks:
Key Insights:
Query: "Place a bull call spread using AAPL June 6th options: one with a 190.00 strike and the other with a 200.00 strike."
Response: Order Details:
Spread Legs:
Long Leg (BUY):
Short Leg (SELL):
Strategy Summary:
These examples demonstrate the server's ability to provide:
The server maintains this level of detail and formatting across all supported queries, making it easy to understand and act on the information provided.
For users who need to run the MCP server on a remote machine (e.g., Ubuntu server) and connect from a different machine (e.g., Windows Claude Desktop), use HTTP transport:
# Start server with HTTP transport (default: 127.0.0.1:8000)
python alpaca_mcp_server.py --transport http
# Start server with custom host/port for remote access
python alpaca_mcp_server.py --transport http --host 0.0.0.0 --port 9000
# For systemd service (example from GitHub issue #6)
# Update your start script to use HTTP transport
#!/bin/bash
cd /root/alpaca-mcp-server
source venv/bin/activate
exec python3 -u alpaca_mcp_server.py --transport http --host 0.0.0.0 --port 8000
Remote Access Options:
--host 0.0.0.0
to bind to all interfaces for direct remote accessssh -L 8000:localhost:8000 user@your-server
for secure access (recommended for localhost binding)Update your Claude Desktop configuration to use HTTP:
{
"mcpServers": {
"alpaca": {
"transport": "http",
"url": "http://your-server-ip:8000/mcp",
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
--transport http
--host 0.0.0.0
for direct access, or SSH tunneling for localhost binding--port <PORT>
to specify a different port if default is busyThis 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.
The user agent for API calls defaults to 'ALPACA-MCP-SERVER' to help Alpaca identify MCP server usage and improve user experience. You can opt out by modifying the 'USER_AGENT' constant in '.github/core/user_agent_mixin.py' or by removing the 'UserAgentMixin' from the client class definitions in 'alpaca_mcp_server.py' β though we kindly hope you'll keep it enabled to support ongoing improvements.
MIT
Please note that the content on this page is for informational purposes only. Alpaca does not recommend any specific securities or investment strategies.
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.
This is not an offer, solicitation of an offer, or advice to buy or sell securities or open a brokerage account in any jurisdiction where Alpaca Securities is not registered or licensed, as applicable.