Alpaca Official MCP Server

@alpacahq

9 months ago

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.

Overview Tools Comments

Overview

Installation

0. Prerequisites

Python (version requirements can be found at: https://modelcontextprotocol.io/quickstart/server)
GitHub account
Alpaca API keys (with paper or live trading access)
Claude for Desktop or another compatible MCP client

1. Installation

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.

Project Structure

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

2. Create and edit a .env file for your credentials in the project directory

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

3. Start the MCP Server

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.

Try in Playground

Server Config

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

Build with ShipAny.