<p align="center">
<img src="https://raw.githubusercontent.com/alpacahq/alpaca-mcp-server/main/assets/01-primary-alpaca-logo.png" alt="Alpaca logo" width="220">
</p>
<div align="center">
<a href="https://x.com/alpacahq?lang=en" target="_blank"><img src="https://img.shields.io/badge/X-DCDCDC?logo=x&logoColor=000" alt="X"></a>
<a href="https://www.reddit.com/r/alpacamarkets/" target="_blank"><img src="https://img.shields.io/badge/Reddit-DCDCDC?logo=reddit&logoColor=000" alt="Reddit"></a>
<a href="https://alpaca.markets/slack" target="_blank"><img src="https://img.shields.io/badge/Slack-DCDCDC?logo=slack&logoColor=000" alt="Slack"></a>
<a href="https://www.linkedin.com/company/alpacamarkets/" target="_blank"><img src="https://img.shields.io/badge/LinkedIn-DCDCDC" alt="LinkedIn"></a>
<a href="https://forum.alpaca.markets/" target="_blank"><img src="https://img.shields.io/badge/Forum-DCDCDC?logo=discourse&logoColor=000" alt="Forum"></a>
<a href="https://docs.alpaca.markets/docs/getting-started" target="_blank"><img src="https://img.shields.io/badge/Docs-DCDCDC" alt="Docs"></a>
<a href="https://alpaca.markets/sdks/python/" target="_blank"><img src="https://img.shields.io/badge/Python_SDK-DCDCDC?logo=python&logoColor=000" alt="Python SDK"></a>
</div>
<p align="center">
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.
</p>
## Table of Contents
- [Quick Start](#quick-start)
- [Prerequisites](#prerequisites)
- [Getting Your API Keys](#getting-your-api-keys)
- [Features](#features)
- [Example Natural Language Queries](#example-natural-language-queries)
- [Example Outputs](#example-outputs)
- [Installation Methods](#installation-methods)
- [MCP Client Configuration](#mcp-client-configuration)
- [HTTP Transport for Remote Usage](#http-transport-for-remote-usage)
- [Available Tools](#available-tools)
- [Security Notice](#security-notice)
- [License](#license)
## Quick Start
**One-click installation with uvx from PyPI:**
```bash
# Install and configure
uvx alpaca-mcp-server init
# Start the server
uvx alpaca-mcp-server serve
```
**Then add to your MCP client config** :
**Config file locations:**
- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
- **Cursor**: `~/.cursor/mcp.json` (Mac/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows)
```json
{
"mcpServers": {
"alpaca": {
"command": "uvx",
"args": ["alpaca-mcp-server", "serve"],
"env": {
"ALPACA_API_KEY": "your_api_key",
"ALPACA_SECRET_KEY": "your_secret_key"
}
}
}
}
```
## Prerequisites
- **Python 3.10+**
- **Alpaca Trading API keys** (free paper trading account)
- **MCP client** (Claude Desktop, Cursor, VS Code, etc.)
## Getting Your API Keys
1. Visit [Alpaca Markets](https://app.alpaca.markets/paper/dashboard/overview)
2. Create a free paper trading account
3. Generate API keys from the dashboard
4. Use these keys when running `uvx alpaca-mcp-server init`
## Features
- **Market Data**
- Real-time quotes, trades, and price bars for stocks, crypto, and options
- Historical data with flexible timeframes (1Min to 1Month)
- Comprehensive stock snapshots and trade-level history
- Option contract quotes and Greeks
- **Account Management**
- View balances, buying power, and account status
- Inspect all open and closed positions
- **Position Management**
- Get detailed info on individual holdings
- Liquidate all or partial positions by share count or percentage
- **Order Management**
- Place stocks, ETFs, crypto, and options orders
- Support for market, limit, stop, stop-limit, and trailing-stop orders
- Cancel orders individually or in bulk
- Retrieve full order history
- **Options Trading**
- Search option contracts by expiration, strike price, and type
- Place single-leg or multi-leg options strategies (spreads, straddles, etc.)
- Get latest quotes, Greeks, and implied volatility
- **Crypto Trading**
- Place market, limit, and stop-limit crypto orders
- Support for GTC and IOC time in force
- Handle quantity or notional-based orders
- **Market Status & Corporate Actions**
- Check if markets are open
- Fetch market calendar and trading sessions
- View upcoming / historical corporate announcements (earnings, splits, dividends)
- **Watchlist Management**
- Create, update, and view personal watchlists
- Manage multiple watchlists for tracking assets
- **Asset Search**
- Query details for stocks, ETFs, crypto, and options
- Filter assets by status, class, exchange, and attributes
## Example Natural Language Queries
<details open>
<summary><b>Basic Trading</b></summary>
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.
</details>
<details>
<summary><b>Crypto Trading</b></summary>
11. Place a market order to buy 0.01 ETH/USD.
12. Place a limit order to sell 0.01 BTC/USD at $110,000.
</details>
<details>
<summary><b>Option Trading</b></summary>
13. Show me available option contracts for AAPL expiring next month.
14. Get the latest quote for the AAPL250613C00200000 option.
15. Retrieve the option snapshot for the SPY250627P00400000 option.
16. Liquidate my position in 2 contracts of QQQ calls expiring next week.
17. Place a market order to buy 1 call option on AAPL expiring next Friday.
18. What are the option Greeks for the TSLA250620P00500000 option?
19. Find TSLA option contracts with strike prices within 5% of the current market price.
20. Get SPY call options expiring the week of June 16th, 2025, within 10% of market price.
21. Place a bull call spread using AAPL June 6th options: one with a 190.00 strike and the other with a 200.00 strike.
22. Exercise my NVDA call option contract NVDA250919C001680.
</details>
<details>
<summary><b>Market Information</b></summary>
> To access the latest 15-minute data, you need to subscribe to the [Algo Trader Plus Plan](https://alpaca.markets/data).
23. What are the market open and close times today?
24. Show me the market calendar for next week.
25. Show me recent cash dividends and stock splits for AAPL, MSFT, and GOOGL in the last 3 months.
26. Get all corporate actions for SPY including dividends, splits, and any mergers in the past year.
27. What are the upcoming corporate actions scheduled for SPY in the next 6 months?
</details>
<details>
<summary><b>Historical & Real-time Data</b></summary>
28. Show me AAPL's daily price history for the last 5 trading days.
29. What was the closing price of TSLA yesterday?
30. Get the latest bar for GOOGL.
31. What was the latest trade price for NVDA?
32. Show me the most recent quote for MSFT.
33. Retrieve the last 100 trades for AMD.
34. Show me 1-minute bars for AMZN from the last 2 hours.
35. Get 5-minute intraday bars for TSLA from last Tuesday through last Friday.
36. Get a comprehensive stock snapshot for AAPL showing latest quote, trade, minute bar, daily bar, and previous daily bar all in one view.
37. Compare market snapshots for TSLA, NVDA, and MSFT to analyze their current bid/ask spreads, latest trade prices, and daily performance.
</details>
<details>
<summary><b>Orders</b></summary>
38. Show me all my open and filled orders from this week.
39. What orders do I have for AAPL?
40. List all limit orders I placed in the past 3 days.
41. Filter all orders by status: filled.
42. Get me the order history for yesterday.
</details>
<details>
<summary><b>Watchlists</b></summary>
> At this moment, you can only view and update trading watchlists created via Alpaca’s Trading API through the API itself
43. Create a new watchlist called "Tech Stocks" with AAPL, MSFT, and NVDA.
44. Update my "Tech Stocks" watchlist to include TSLA and AMZN.
45. What stocks are in my "Dividend Picks" watchlist?
46. Remove META from my "Growth Portfolio" watchlist.
47. List all my existing watchlists.
</details>
<details>
<summary><b>Asset Information</b></summary>
48. Search for details about the asset 'AAPL'.
49. Show me the top 5 tradable crypto assets by trading volume.
50. Get all NASDAQ active US equity assets and filter the results to show only tradable securities
</details>
<details>
<summary><b>Combined Scenarios</b></summary>
51. Get today's market clock and show me my buying power before placing a limit buy order for TSLA at $340.
52. Place a bull call spread with SPY July 3rd options: sell one 5% above and buy one 3% below the current SPY price.
</details>
## Example Outputs
<details>
<summary><b>View Example Outputs</b></summary>
The MCP server provides detailed, well-formatted responses for various trading queries. Here are some examples:
### Option Greeks Analysis
Query: "What are the option Greeks for TSLA250620P00500000?"
Response:
Option Details:
- Current Bid/Ask: $142.62 / $143.89
- Last Trade: $138.85
- Implied Volatility: 92.54%
Greeks:
- Delta: -0.8968 (Very Bearish)
- Gamma: 0.0021 (Low Rate of Change)
- Theta: -0.2658 (Time Decay: $26.58/day)
- Vega: 0.1654 (Volatility Sensitivity)
- Rho: -0.3060 (Interest Rate Sensitivity)
Key Insights:
- High Implied Volatility (92.54%)
- Deep In-the-Money (Delta: -0.90)
- Significant Time Decay ($27/day)
### Multi-Leg Option Order
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:
- Order ID: fc1c04b1-8afa-4b2d-aab1-49613bbed7cb
- Order Class: Multi-Leg (MLEG)
- Status: Pending New
- Quantity: 1 spread
Spread Legs:
1. Long Leg (BUY):
- AAPL250606C00190000 ($190.00 strike)
- Status: Pending New
2. Short Leg (SELL):
- AAPL250606C00200000 ($200.00 strike)
- Status: Pending New
Strategy Summary:
- Max Profit: $10.00 per spread
- Max Loss: Net debit paid
- Breakeven: $190 + net debit paid
These examples demonstrate the server's ability to provide:
- Detailed market data analysis
- Comprehensive order execution details
- Clear strategy explanations
- Well-formatted, easy-to-read responses
</details>
## Installation Methods
### 1. Choose Your Installation Method
This section shows manual installation of Alpaca MCP Server.
#### Method 1: uvx
```bash
# Install and configure
uvx alpaca-mcp-server init
# Start the server
uvx alpaca-mcp-server serve
```
#### Method 2: pip
```bash
# Install from PyPI
pip install alpaca-mcp-server
# Configure and run
alpaca-mcp init
alpaca-mcp serve
```
#### Method 3: Docker
```bash
# Run with Docker
docker run -e ALPACA_API_KEY=your_key -e ALPACA_SECRET_KEY=your_secret alpaca/mcp-server
```
#### Method 4: Development Installation
<details>
<summary><b>Expand for Development Installation Instructions</b></summary>
**Option A: Using pip (traditional)**
```bash
# Clone and install for development
git clone https://github.com/idsts2670/alpaca-mcp-server
# Move to the cloned repository
cd alpaca-mcp-server
# Create the virtual environment first
python3 -m venv .venv
# Activate the virtual environment
source .venv/bin/activate
# Configure the
pip install -e .
```
**Option B: Using uv (modern, faster)**
To use uv, you'll first need to install it. See the [official uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for detailed installation instructions for your platform.
```bash
# Clone and install for development
git clone https://github.com/idsts2670/alpaca-mcp-server
# Create the virtual environment first
uv venv .venv
# Activate the virtual environment
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Configures the development environment
uv pip install -e .
```
**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.
</details>
### 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
1. Copy the example environment file in the project root by running this command:
```bash
cp .env.example .env
```
2. 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
TRADE_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 the case of configurating with uvx from PyPI:**
```bash
uvx alpaca-mcp-server serve # When configuring with `uvx` from PyPI
```
**For local usage (default - stdio transport):**
```bash
python alpaca_mcp_server.py # When configuring with `uv` or `pip`
```
**For remote usage (HTTP transport):**
```bash
python alpaca_mcp_server.py --transport http # When configuring with `uv` or `pip`
```
**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](https://modelcontextprotocol.io/docs/concepts/transports).
### 4. Switching API Keys for Live Trading
This MCP server connects to Alpaca's **paper Trading API** by default for safe testing.
To enable **live trading with real funds** or switch between different accounts, you need to update API credentials in **two places**:
1. **`.env` file** (used by MCP server)
2. **MCP client config JSON** (used by MCP client like Claude Desktop, Cursor, etc.)
**Important:** The MCP client configuration overrides the `.env` file. When using an MCP client, the credentials in the client's JSON config take precedence.
#### Place 1: Update `.env` File (Used by MCP Server)
**For direct CLI usage or when running the server directly:**
**Option 1: Run the init command again** to update your `.env` file:
```bash
uvx alpaca-mcp-server init
# Follow the prompts to update your keys and toggle paper/live trading
```
**Option 2: Manually edit** the `.env` file in your current directory:
```
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
```
#### Place 2: Update MCP Client Config (Used by MCP Client)
**For MCP client users (Claude Desktop, Cursor, VS Code, etc.):**
**Step 1: Edit your MCP client configuration file**:
- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
- **Cursor**: `~/.cursor/mcp.json`
- **VS Code**: `.vscode/mcp.json` (workspace) or user `settings.json`
**Step 2: Update the API keys** in the `env` section:
**For uvx installations:**
```json
{
"mcpServers": {
"alpaca": {
"command": "uvx",
"args": ["alpaca-mcp-server", "serve"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key_for_live_account",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key_for_live_account"
}
}
}
}
```
**For legacy/development installations:**
```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"
}
}
}
}
```
**Step 3: Restart your MCP client** (Claude Desktop, Cursor, etc.)
## MCP Client Configuration
Below you'll find step-by-step guides for connecting the Alpaca MCP server to various MCP clients. Choose the section that matches your preferred development environment or AI assistant.
<details open>
<summary><b>Claude Desktop Configuration</b></summary>
### Claude Desktop Configuration
#### Method 1: uvx (Recommended)
**Simple and modern approach:**
1. Install and configure the server:
```bash
uvx alpaca-mcp-server init
```
2. Open Claude Desktop → Settings → Developer → Edit Config
3. Add this configuration:
```json
{
"mcpServers": {
"alpaca": {
"command": "uvx",
"args": ["alpaca-mcp-server", "serve"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
```
4. Restart Claude Desktop and start trading!
<details>
<summary><b>Method 2: Legacy Installation (Deprecated)</b></summary>
#### Method 2: Legacy Installation (Deprecated)
> ⚠️ **This method is deprecated.** Please use the uvx method above for new installations.
**For existing installations (stdio transport):**
```json
{
"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):**
```json
{
"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"
}
}
}
}
```
</details>
</details>
<details>
<summary><b>Claude Code Usage</b></summary>
### Claude Code Usage
To use Alpaca MCP Server with Claude Code, please follow the steps below.
The `claude mcp add command` is part of [Claude Code](https://www.anthropic.com/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:
```bash
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
* [Learn how to set up MCP with Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp)
* [Install, authenticate, and start using Claude Code on your development machine](https://docs.anthropic.com/en/docs/claude-code/setup)
</details>
<details>
<summary><b>Cursor Usage</b></summary>
### Cursor Usage
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**
- Cursor IDE installed with Claude AI enabled
- Python and virtual environment set up (follow Installation steps above)
#### Configure the MCP Server
**Method 1: Using JSON Configuration**
Create or edit `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows):
```json
{
"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**
1. Open Cursor Settings → **Tools & Integrations** → **MCP Tools**
2. Click **"+ New MCP Server"**
3. Configure with the same details as the JSON method above
**Note:** Replace the paths with your actual project directory paths and API credentials.
</details>
<details>
<summary><b>VS Code Usage</b></summary>
### VS Code Usage
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**
- VS Code with GitHub Copilot extension installed and active subscription
- Python and virtual environment set up (follow Installation steps above)
- MCP support enabled in VS Code (see below)
#### 1. Enable MCP Support in VS Code
1. Open VS Code Settings (Ctrl/Cmd + ,)
2. Search for "chat.mcp.enabled" to check the box to enable MCP support
3. Search for "github.copilot.chat.experimental.mcp" to check the box to use instruction files
#### 2. Configure the MCP Server
**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:**
1. Create `.vscode/mcp.json` in your project root.
2. Add the Alpaca MCP server configuration manually to the mcp.json file:
For Linux/macOS:
```json
{
"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:
```json
{
"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:
- Linux/macOS: `/Users/username/Documents/alpaca-mcp-server`
- Windows: `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.
```json
{
"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"
}
}
}
}
}
```
</details>
<details>
<summary><b>PyCharm Usage</b></summary>
### PyCharm Usage
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.
1. **Open PyCharm Settings**
- Go to `File → Settings`
- Navigate to `Tools → Model Context Protocol (MCP)` (or similar location depending on PyCharm version)
2. **Add New MCP Server**
- Click `Add` or `+` to create a new server configuration. You can also import the settings from Claude by clicking the corresponding button.
- **Name**: Enter any name you prefer for this server configuration (e.g., Alpaca MCP).
- **Command**: "/path/to/your/alpaca-mcp-server/venv/bin/python"
- **Arguments**: "alpaca_mcp_server.py"
- **Working directory**: "/path/to/your/alpaca-mcp-server"
3. **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
```
</details>
<details>
<summary><b>Docker Usage</b></summary>
### Docker Usage
To use Alpaca MCP Server with Docker, please follow the steps below.
**Prerequisite:**
You must have [Docker installed](https://docs.docker.com/get-docker/) on your system.
#### Build and run locally (recommended)
```bash
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
```
This builds and runs the server from your local source code.
#### HTTP mode example
```bash
docker run --rm -p 8000:8000 alpaca-mcp-server --transport http
```
#### Alternative: Use published image (if available)
```bash
docker run --pull=always -it --rm \
-e ALPACA_API_KEY=your_alpaca_api_key \
-e ALPACA_SECRET_KEY=your_alpaca_secret_key \
ghcr.io/alpacahq/alpaca-mcp-server:latest
```
**Note:** Verify the published image exists and is maintained before using.
#### Using with Claude Desktop
```json
{
"mcpServers": {
"alpaca": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "ALPACA_API_KEY",
"-e", "ALPACA_SECRET_KEY",
"alpaca-mcp-server"
],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
```
Provide values via the MCP client's env block, and use -e VAR flags to forward them into the Docker container. Avoid hardcoding secrets directly in args.
#### Alternative credential methods
```bash
# Using an env file
docker run --env-file .env alpaca-mcp-server
# Bind mounting a .env file
docker run -v $(pwd)/.env:/app/.env:ro alpaca-mcp-server
```
**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](https://docs.docker.com/).
</details>
## HTTP Transport for Remote Usage
<details>
<summary><b>Expand for Remote Server Setup Instructions</b></summary>
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:
### Server Setup (Remote Machine)
```bash
# 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:**
1. **Direct binding**: Use `--host 0.0.0.0` to bind to all interfaces for direct remote access
2. **SSH tunneling**: `ssh -L 8000:localhost:8000 user@your-server` for secure access (recommended for localhost binding)
3. **Reverse proxy**: Use nginx/Apache to expose the service securely with authentication
### Client Setup
Update your Claude Desktop configuration to use HTTP:
```json
{
"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"
}
}
}
}
```
### Troubleshooting HTTP Transport Issues
- **Port not listening**: Ensure the server started successfully and check firewall settings
- **Connection refused**: Verify the server is running on the expected host:port
- **ENOENT errors**: Make sure you're using the updated server command with `--transport http`
- **Remote access**: Use `--host 0.0.0.0` for direct access, or SSH tunneling for localhost binding
- **Port conflicts**: Use `--port <PORT>` to specify a different port if default is busy
</details>
## Available Tools
<details>
<summary><b>View All Available Tools</b></summary>
### Account & Positions
* `get_account_info()` – View balance, margin, and account status
* `get_positions()` – List all held assets
* `get_open_position(symbol)` – Detailed info on a specific position
* `close_position(symbol, qty|percentage)` – Close part or all of a position
* `close_all_positions(cancel_orders)` – Liquidate entire portfolio
### Stock Market Data
* `get_stock_quote(symbol)` – Real-time bid/ask quote
* `get_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 price
* `get_stock_latest_bar(symbol, feed=None, currency=None)` – Most recent OHLC bar
* `get_stock_snapshot(symbol_or_symbols, feed=None, currency=None)` – Comprehensive snapshot with latest quote, trade, minute bar, daily bar, and previous daily bar
* `get_stock_trades(symbol, days=5, limit=None, sort=Sort.ASC, feed=None, currency=None, asof=None)` – Trade-level history
### Orders
* `get_orders(status, limit)` – Retrieve all or filtered orders
* `place_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 order
* `cancel_all_orders()` – Cancel all open orders
### Crypto
* `place_crypto_order(symbol, side, order_type="market", time_in_force="gtc", qty=None, notional=None, limit_price=None, stop_price=None, client_order_id=None)` – Place a crypto order supporting market, limit, and stop_limit types with GTC/IOC time in force
### Options
* `get_option_contracts(underlying_symbol, expiration_date=None, expiration_date_gte=None, expiration_date_lte=None, expiration_expression=None, strike_price_gte=None, strike_price_lte=None, type=None, status=None, root_symbol=None, limit=None)` – – Get option contracts with flexible filtering.
* `get_option_latest_quote(option_symbol)` – Latest bid/ask on contract
* `get_option_snapshot(symbol_or_symbols)` – Get Greeks and underlying
* `place_option_market_order(legs, order_class=None, quantity=1, time_in_force=TimeInForce.DAY, extended_hours=False)` – Execute option strategy
* `exercise_options_position(symbol_or_contract_id)` – Exercise a held option contract, converting it into the underlying asset
### Market Info & Corporate Actions
* `get_market_clock()` – Market open/close schedule
* `get_market_calendar(start, end)` – Holidays and trading days
* `get_corporate_announcements(ca_types, start, end, symbols)` – Historical and future corporate actions (e.g., earnings, dividends, splits)
### Watchlists
* `create_watchlist(name, symbols)` – Create a new list
* `update_watchlist(watchlist_id, name=None, symbols=None)` – Modify an existing list
* `get_watchlists()` – Retrieve all saved watchlists
### Assets
* `get_asset_info(symbol)` – Search asset metadata
* `get_all_assets(status=None, asset_class=None, exchange=None, attributes=None)` – List all tradable instruments with filtering options
</details>
## 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.
## Usage Analytics Notice
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.
## License
MIT License - See [LICENSE](LICENSE) file for details
## Disclosure
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](https://www.theocc.com/company-information/documents-and-archives/options-disclosure-document?ref=alpaca.markets)) 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](https://www.finra.org/)/[SIPC](https://www.sipc.org/), 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "alpaca-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, alpaca, finance, llm, mcp, model-context-protocol, trading",
"author": null,
"author_email": "Alpaca <info@alpaca.markets>",
"download_url": "https://files.pythonhosted.org/packages/6e/a3/3653499263602722a1ccd3bec3e39127384a2d592a2eff42e8bbce1a2fe8/alpaca_mcp_server-1.0.2.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/alpacahq/alpaca-mcp-server/main/assets/01-primary-alpaca-logo.png\" alt=\"Alpaca logo\" width=\"220\">\n</p>\n\n<div align=\"center\">\n\n<a href=\"https://x.com/alpacahq?lang=en\" target=\"_blank\"><img src=\"https://img.shields.io/badge/X-DCDCDC?logo=x&logoColor=000\" alt=\"X\"></a>\n<a href=\"https://www.reddit.com/r/alpacamarkets/\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Reddit-DCDCDC?logo=reddit&logoColor=000\" alt=\"Reddit\"></a>\n<a href=\"https://alpaca.markets/slack\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Slack-DCDCDC?logo=slack&logoColor=000\" alt=\"Slack\"></a>\n<a href=\"https://www.linkedin.com/company/alpacamarkets/\" target=\"_blank\"><img src=\"https://img.shields.io/badge/LinkedIn-DCDCDC\" alt=\"LinkedIn\"></a>\n<a href=\"https://forum.alpaca.markets/\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Forum-DCDCDC?logo=discourse&logoColor=000\" alt=\"Forum\"></a>\n<a href=\"https://docs.alpaca.markets/docs/getting-started\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Docs-DCDCDC\" alt=\"Docs\"></a>\n<a href=\"https://alpaca.markets/sdks/python/\" target=\"_blank\"><img src=\"https://img.shields.io/badge/Python_SDK-DCDCDC?logo=python&logoColor=000\" alt=\"Python SDK\"></a>\n\n</div>\n\n<p align=\"center\">\n 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.\n</p>\n\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Prerequisites](#prerequisites)\n- [Getting Your API Keys](#getting-your-api-keys)\n- [Features](#features)\n- [Example Natural Language Queries](#example-natural-language-queries)\n- [Example Outputs](#example-outputs)\n- [Installation Methods](#installation-methods)\n- [MCP Client Configuration](#mcp-client-configuration)\n- [HTTP Transport for Remote Usage](#http-transport-for-remote-usage)\n- [Available Tools](#available-tools)\n- [Security Notice](#security-notice)\n- [License](#license)\n\n## Quick Start\n\n**One-click installation with uvx from PyPI:**\n\n```bash\n# Install and configure\nuvx alpaca-mcp-server init\n\n# Start the server\nuvx alpaca-mcp-server serve\n```\n\n**Then add to your MCP client config** :\n\n**Config file locations:**\n- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n- **Cursor**: `~/.cursor/mcp.json` (Mac/Linux) or `%USERPROFILE%\\.cursor\\mcp.json` (Windows)\n\n```json\n{\n \"mcpServers\": {\n \"alpaca\": {\n \"command\": \"uvx\",\n \"args\": [\"alpaca-mcp-server\", \"serve\"],\n \"env\": {\n \"ALPACA_API_KEY\": \"your_api_key\",\n \"ALPACA_SECRET_KEY\": \"your_secret_key\"\n }\n }\n }\n}\n```\n\n## Prerequisites\n\n- **Python 3.10+** \n- **Alpaca Trading API keys** (free paper trading account)\n- **MCP client** (Claude Desktop, Cursor, VS Code, etc.)\n\n## Getting Your API Keys\n\n1. Visit [Alpaca Markets](https://app.alpaca.markets/paper/dashboard/overview)\n2. Create a free paper trading account\n3. Generate API keys from the dashboard\n4. Use these keys when running `uvx alpaca-mcp-server init`\n\n## Features\n\n- **Market Data**\n - Real-time quotes, trades, and price bars for stocks, crypto, and options\n - Historical data with flexible timeframes (1Min to 1Month)\n - Comprehensive stock snapshots and trade-level history\n - Option contract quotes and Greeks\n- **Account Management**\n - View balances, buying power, and account status\n - Inspect all open and closed positions\n- **Position Management**\n - Get detailed info on individual holdings\n - Liquidate all or partial positions by share count or percentage\n- **Order Management**\n - Place stocks, ETFs, crypto, and options orders\n - Support for market, limit, stop, stop-limit, and trailing-stop orders\n - Cancel orders individually or in bulk\n - Retrieve full order history\n- **Options Trading**\n - Search option contracts by expiration, strike price, and type\n - Place single-leg or multi-leg options strategies (spreads, straddles, etc.)\n - Get latest quotes, Greeks, and implied volatility\n- **Crypto Trading**\n - Place market, limit, and stop-limit crypto orders\n - Support for GTC and IOC time in force\n - Handle quantity or notional-based orders\n- **Market Status & Corporate Actions**\n - Check if markets are open\n - Fetch market calendar and trading sessions\n - View upcoming / historical corporate announcements (earnings, splits, dividends)\n- **Watchlist Management**\n - Create, update, and view personal watchlists\n - Manage multiple watchlists for tracking assets\n- **Asset Search**\n - Query details for stocks, ETFs, crypto, and options\n - Filter assets by status, class, exchange, and attributes\n\n## Example Natural Language Queries\n\n<details open>\n<summary><b>Basic Trading</b></summary>\n\n\n1. What's my current account balance and buying power on Alpaca?\n2. Show me my current positions in my Alpaca account.\n3. Buy 5 shares of AAPL at market price.\n4. Sell 5 shares of TSLA with a limit price of $300.\n5. Cancel all open stock orders.\n6. Cancel the order with ID abc123.\n7. Liquidate my entire position in GOOGL.\n8. Close 10% of my position in NVDA.\n9. Place a limit order to buy 100 shares of MSFT at $450.\n10. Place a market order to sell 25 shares of META.\n\n</details>\n\n<details>\n<summary><b>Crypto Trading</b></summary>\n\n11. Place a market order to buy 0.01 ETH/USD.\n12. Place a limit order to sell 0.01 BTC/USD at $110,000.\n\n</details>\n\n<details>\n<summary><b>Option Trading</b></summary>\n\n13. Show me available option contracts for AAPL expiring next month.\n14. Get the latest quote for the AAPL250613C00200000 option.\n15. Retrieve the option snapshot for the SPY250627P00400000 option.\n16. Liquidate my position in 2 contracts of QQQ calls expiring next week.\n17. Place a market order to buy 1 call option on AAPL expiring next Friday.\n18. What are the option Greeks for the TSLA250620P00500000 option?\n19. Find TSLA option contracts with strike prices within 5% of the current market price.\n20. Get SPY call options expiring the week of June 16th, 2025, within 10% of market price.\n21. Place a bull call spread using AAPL June 6th options: one with a 190.00 strike and the other with a 200.00 strike.\n22. Exercise my NVDA call option contract NVDA250919C001680.\n\n</details>\n\n<details>\n<summary><b>Market Information</b></summary>\n\n> To access the latest 15-minute data, you need to subscribe to the [Algo Trader Plus Plan](https://alpaca.markets/data).\n23. What are the market open and close times today?\n24. Show me the market calendar for next week.\n25. Show me recent cash dividends and stock splits for AAPL, MSFT, and GOOGL in the last 3 months.\n26. Get all corporate actions for SPY including dividends, splits, and any mergers in the past year.\n27. What are the upcoming corporate actions scheduled for SPY in the next 6 months?\n\n</details>\n\n<details>\n<summary><b>Historical & Real-time Data</b></summary>\n\n28. Show me AAPL's daily price history for the last 5 trading days.\n29. What was the closing price of TSLA yesterday?\n30. Get the latest bar for GOOGL.\n31. What was the latest trade price for NVDA?\n32. Show me the most recent quote for MSFT.\n33. Retrieve the last 100 trades for AMD.\n34. Show me 1-minute bars for AMZN from the last 2 hours.\n35. Get 5-minute intraday bars for TSLA from last Tuesday through last Friday.\n36. Get a comprehensive stock snapshot for AAPL showing latest quote, trade, minute bar, daily bar, and previous daily bar all in one view.\n37. Compare market snapshots for TSLA, NVDA, and MSFT to analyze their current bid/ask spreads, latest trade prices, and daily performance.\n\n</details>\n\n<details>\n<summary><b>Orders</b></summary>\n\n38. Show me all my open and filled orders from this week.\n39. What orders do I have for AAPL?\n40. List all limit orders I placed in the past 3 days.\n41. Filter all orders by status: filled.\n42. Get me the order history for yesterday.\n\n</details>\n\n<details>\n<summary><b>Watchlists</b></summary>\n\n> At this moment, you can only view and update trading watchlists created via Alpaca\u2019s Trading API through the API itself\n43. Create a new watchlist called \"Tech Stocks\" with AAPL, MSFT, and NVDA.\n44. Update my \"Tech Stocks\" watchlist to include TSLA and AMZN.\n45. What stocks are in my \"Dividend Picks\" watchlist?\n46. Remove META from my \"Growth Portfolio\" watchlist.\n47. List all my existing watchlists.\n\n</details>\n\n<details>\n<summary><b>Asset Information</b></summary>\n\n48. Search for details about the asset 'AAPL'.\n49. Show me the top 5 tradable crypto assets by trading volume.\n50. Get all NASDAQ active US equity assets and filter the results to show only tradable securities\n\n</details>\n\n<details>\n<summary><b>Combined Scenarios</b></summary>\n\n51. Get today's market clock and show me my buying power before placing a limit buy order for TSLA at $340.\n52. Place a bull call spread with SPY July 3rd options: sell one 5% above and buy one 3% below the current SPY price.\n\n</details>\n\n## Example Outputs\n\n<details>\n<summary><b>View Example Outputs</b></summary>\n\nThe MCP server provides detailed, well-formatted responses for various trading queries. Here are some examples:\n\n### Option Greeks Analysis\nQuery: \"What are the option Greeks for TSLA250620P00500000?\"\n\nResponse:\nOption Details:\n- Current Bid/Ask: $142.62 / $143.89\n- Last Trade: $138.85\n- Implied Volatility: 92.54%\n\nGreeks:\n- Delta: -0.8968 (Very Bearish)\n- Gamma: 0.0021 (Low Rate of Change)\n- Theta: -0.2658 (Time Decay: $26.58/day)\n- Vega: 0.1654 (Volatility Sensitivity)\n- Rho: -0.3060 (Interest Rate Sensitivity)\n\nKey Insights:\n- High Implied Volatility (92.54%)\n- Deep In-the-Money (Delta: -0.90)\n- Significant Time Decay ($27/day)\n\n### Multi-Leg Option Order\nQuery: \"Place a bull call spread using AAPL June 6th options: one with a 190.00 strike and the other with a 200.00 strike.\"\n\nResponse:\nOrder Details:\n- Order ID: fc1c04b1-8afa-4b2d-aab1-49613bbed7cb\n- Order Class: Multi-Leg (MLEG)\n- Status: Pending New\n- Quantity: 1 spread\n\nSpread Legs:\n1. Long Leg (BUY):\n - AAPL250606C00190000 ($190.00 strike)\n - Status: Pending New\n\n2. Short Leg (SELL):\n - AAPL250606C00200000 ($200.00 strike)\n - Status: Pending New\n\nStrategy Summary:\n- Max Profit: $10.00 per spread\n- Max Loss: Net debit paid\n- Breakeven: $190 + net debit paid\n\nThese examples demonstrate the server's ability to provide:\n- Detailed market data analysis\n- Comprehensive order execution details\n- Clear strategy explanations\n- Well-formatted, easy-to-read responses\n\n</details>\n\n## Installation Methods\n\n### 1. Choose Your Installation Method\nThis section shows manual installation of Alpaca MCP Server.\n\n#### Method 1: uvx\n\n ```bash\n # Install and configure\n uvx alpaca-mcp-server init\n\n # Start the server\n uvx alpaca-mcp-server serve\n ```\n\n#### Method 2: pip\n\n ```bash\n # Install from PyPI\n pip install alpaca-mcp-server\n\n # Configure and run\n alpaca-mcp init\n alpaca-mcp serve\n ```\n\n#### Method 3: Docker\n\n ```bash\n # Run with Docker\n docker run -e ALPACA_API_KEY=your_key -e ALPACA_SECRET_KEY=your_secret alpaca/mcp-server\n ```\n\n#### Method 4: Development Installation\n\n<details>\n<summary><b>Expand for Development Installation Instructions</b></summary>\n\n **Option A: Using pip (traditional)**\n ```bash\n # Clone and install for development\n git clone https://github.com/idsts2670/alpaca-mcp-server\n # Move to the cloned repository\n cd alpaca-mcp-server\n # Create the virtual environment first\n python3 -m venv .venv\n # Activate the virtual environment\n source .venv/bin/activate\n # Configure the \n pip install -e .\n ```\n\n **Option B: Using uv (modern, faster)**\n\n To use uv, you'll first need to install it. See the [official uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for detailed installation instructions for your platform.\n ```bash\n # Clone and install for development\n git clone https://github.com/idsts2670/alpaca-mcp-server\n # Create the virtual environment first\n uv venv .venv\n # Activate the virtual environment\n source .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n # Configures the development environment\n uv pip install -e .\n ```\n **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. \n\n</details>\n\n### Project Structure\n\nAfter cloning and activating the virtual environment, your directory structure should look like this:\n```\nalpaca-mcp-server/ \u2190 This is the workspace folder (= project root)\n\u251c\u2500\u2500 alpaca_mcp_server.py \u2190 Script is directly in workspace root\n\u251c\u2500\u2500 .github/ \u2190 VS Code settings (for VS Code users)\n\u2502 \u251c\u2500\u2500 core/ \u2190 Core utility modules\n\u2502 \u2514\u2500\u2500 workflows/ \u2190 GitHub Actions workflows\n\u251c\u2500\u2500 .vscode/ \u2190 VS Code settings (for VS Code users)\n\u2502 \u2514\u2500\u2500 mcp.json\n\u251c\u2500\u2500 venv/ \u2190 Virtual environment folder\n\u2502 \u2514\u2500\u2500 bin/python\n\u251c\u2500\u2500 .env.example \u2190 Environment template (use this to create `.env` file)\n\u251c\u2500\u2500 .gitignore \n\u251c\u2500\u2500 Dockerfile \u2190 Docker configuration (for Docker use)\n\u251c\u2500\u2500 .dockerignore \u2190 Docker ignore (for Docker use)\n\u251c\u2500\u2500 requirements.txt \n\u2514\u2500\u2500 README.md\n```\n\n### 2. Create and edit a .env file for your credentials in the project directory\n\n1. Copy the example environment file in the project root by running this command:\n ```bash\n cp .env.example .env\n ```\n\n2. Replace the credentials (e.g. API keys) in the `.env` file:\n\n ```\n ALPACA_API_KEY = \"your_alpaca_api_key_for_paper_account\"\n ALPACA_SECRET_KEY = \"your_alpaca_secret_key_for_paper_account\"\n ALPACA_PAPER_TRADE = True\n TRADE_API_URL = None\n TRADE_API_WSS = None\n DATA_API_URL = None\n STREAM_DATA_WSS = None\n ```\n\n### 3. Start the MCP Server\n\nOpen a terminal in the project root directory and run the following command:\n\n**For the case of configurating with uvx from PyPI:**\n```bash\nuvx alpaca-mcp-server serve # When configuring with `uvx` from PyPI\n```\n\n**For local usage (default - stdio transport):**\n```bash\npython alpaca_mcp_server.py # When configuring with `uv` or `pip`\n```\n\n**For remote usage (HTTP transport):**\n```bash\npython alpaca_mcp_server.py --transport http # When configuring with `uv` or `pip`\n```\n\n**Available transport options:**\n- `--transport stdio` (default): Standard input/output for local client connections\n- `--transport http`: HTTP transport for remote client connections (default: 127.0.0.1:8000)\n- `--transport sse`: Server-Sent Events transport for remote connections (deprecated)\n- `--host HOST`: Host to bind the server to for HTTP/SSE transport (default: 127.0.0.1)\n- `--port PORT`: Port to bind the server to for HTTP/SSE transport (default: 8000)\n\n**Note:** For more information about MCP transport methods, see the [official MCP transport documentation](https://modelcontextprotocol.io/docs/concepts/transports).\n\n### 4. Switching API Keys for Live Trading\n\nThis MCP server connects to Alpaca's **paper Trading API** by default for safe testing.\nTo enable **live trading with real funds** or switch between different accounts, you need to update API credentials in **two places**:\n\n1. **`.env` file** (used by MCP server)\n2. **MCP client config JSON** (used by MCP client like Claude Desktop, Cursor, etc.)\n\n**Important:** The MCP client configuration overrides the `.env` file. When using an MCP client, the credentials in the client's JSON config take precedence.\n\n#### Place 1: Update `.env` File (Used by MCP Server)\n\n**For direct CLI usage or when running the server directly:**\n\n**Option 1: Run the init command again** to update your `.env` file:\n```bash\nuvx alpaca-mcp-server init\n# Follow the prompts to update your keys and toggle paper/live trading\n```\n\n**Option 2: Manually edit** the `.env` file in your current directory:\n```\nALPACA_API_KEY = \"your_alpaca_api_key_for_live_account\"\nALPACA_SECRET_KEY = \"your_alpaca_secret_key_for_live_account\"\nALPACA_PAPER_TRADE = False\nTRADE_API_URL = None\nTRADE_API_WSS = None\nDATA_API_URL = None\nSTREAM_DATA_WSS = None\n```\n\n#### Place 2: Update MCP Client Config (Used by MCP Client)\n\n**For MCP client users (Claude Desktop, Cursor, VS Code, etc.):**\n\n**Step 1: Edit your MCP client configuration file**:\n - **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n - **Cursor**: `~/.cursor/mcp.json`\n - **VS Code**: `.vscode/mcp.json` (workspace) or user `settings.json`\n\n**Step 2: Update the API keys** in the `env` section:\n\n **For uvx installations:**\n ```json\n {\n \"mcpServers\": {\n \"alpaca\": {\n \"command\": \"uvx\",\n \"args\": [\"alpaca-mcp-server\", \"serve\"],\n \"env\": {\n \"ALPACA_API_KEY\": \"your_alpaca_api_key_for_live_account\",\n \"ALPACA_SECRET_KEY\": \"your_alpaca_secret_key_for_live_account\"\n }\n }\n }\n }\n ```\n\n **For legacy/development installations:**\n ```json\n {\n \"mcpServers\": {\n \"alpaca\": {\n \"command\": \"<project_root>/venv/bin/python\",\n \"args\": [\"/path/to/alpaca_mcp_server.py\"],\n \"env\": {\n \"ALPACA_API_KEY\": \"your_alpaca_api_key_for_live_account\",\n \"ALPACA_SECRET_KEY\": \"your_alpaca_secret_key_for_live_account\"\n }\n }\n }\n }\n ```\n\n**Step 3: Restart your MCP client** (Claude Desktop, Cursor, etc.)\n\n\n## MCP Client Configuration\n\nBelow you'll find step-by-step guides for connecting the Alpaca MCP server to various MCP clients. Choose the section that matches your preferred development environment or AI assistant.\n\n<details open>\n<summary><b>Claude Desktop Configuration</b></summary>\n\n### Claude Desktop Configuration\n\n#### Method 1: uvx (Recommended)\n\n**Simple and modern approach:**\n\n1. Install and configure the server:\n ```bash\n uvx alpaca-mcp-server init\n ```\n\n2. Open Claude Desktop \u2192 Settings \u2192 Developer \u2192 Edit Config\n\n3. Add this configuration:\n ```json\n {\n \"mcpServers\": {\n \"alpaca\": {\n \"command\": \"uvx\",\n \"args\": [\"alpaca-mcp-server\", \"serve\"],\n \"env\": {\n \"ALPACA_API_KEY\": \"your_alpaca_api_key\",\n \"ALPACA_SECRET_KEY\": \"your_alpaca_secret_key\"\n }\n }\n }\n }\n ```\n\n4. Restart Claude Desktop and start trading!\n\n<details>\n<summary><b>Method 2: Legacy Installation (Deprecated)</b></summary>\n\n#### Method 2: Legacy Installation (Deprecated)\n\n> \u26a0\ufe0f **This method is deprecated.** Please use the uvx method above for new installations.\n\n**For existing installations (stdio transport):**\n```json\n{\n \"mcpServers\": {\n \"alpaca\": {\n \"command\": \"<project_root>/venv/bin/python\",\n \"args\": [\n \"/path/to/alpaca-mcp-server/alpaca_mcp_server.py\"\n ],\n \"env\": {\n \"ALPACA_API_KEY\": \"your_alpaca_api_key_for_paper_account\",\n \"ALPACA_SECRET_KEY\": \"your_alpaca_secret_key_for_paper_account\"\n }\n }\n }\n}\n```\n\n**For remote usage (HTTP transport):**\n```json\n{\n \"mcpServers\": {\n \"alpaca\": {\n \"transport\": \"http\",\n \"url\": \"http://your-server-ip:8000/mcp\",\n \"env\": {\n \"ALPACA_API_KEY\": \"your_alpaca_api_key_for_paper_account\",\n \"ALPACA_SECRET_KEY\": \"your_alpaca_secret_key_for_paper_account\"\n }\n }\n }\n}\n```\n\n</details>\n\n</details>\n\n<details>\n<summary><b>Claude Code Usage</b></summary>\n\n### Claude Code Usage\n\nTo use Alpaca MCP Server with Claude Code, please follow the steps below.\n\nThe `claude mcp add command` is part of [Claude Code](https://www.anthropic.com/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:\n\n```bash\nclaude mcp add alpaca \\\n /path/to/your/alpaca-mcp-server/venv/bin/python \\\n /path/to/your/alpaca-mcp-server/alpaca_mcp_server.py \\\n -e ALPACA_API_KEY=your_api_key \\\n -e ALPACA_SECRET_KEY=your_secret_key\n```\n\n**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.\n\nThe Claude MCP CLI tool needs to be installed separately. Check following the official pages for availability and installation instructions\n* [Learn how to set up MCP with Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp)\n* [Install, authenticate, and start using Claude Code on your development machine](https://docs.anthropic.com/en/docs/claude-code/setup)\n\n</details>\n\n<details>\n<summary><b>Cursor Usage</b></summary>\n\n### Cursor Usage\n\nTo 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\n\n**Prerequisites**\n- Cursor IDE installed with Claude AI enabled\n- Python and virtual environment set up (follow Installation steps above)\n\n#### Configure the MCP Server\n\n**Method 1: Using JSON Configuration**\n\nCreate or edit `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\\.cursor\\mcp.json` (Windows):\n\n```json\n{\n \"mcpServers\": {\n \"alpaca\": {\n \"command\": \"/path/to/your/alpaca-mcp-server/venv/bin/python\",\n \"args\": [\n \"/path/to/your/alpaca-mcp-server/alpaca_mcp_server.py\"\n ],\n \"env\": {\n \"ALPACA_API_KEY\": \"your_alpaca_api_key\",\n \"ALPACA_SECRET_KEY\": \"your_alpaca_secret_key\"\n }\n }\n }\n}\n```\n\n**Method 2: Using Cursor Settings UI**\n\n1. Open Cursor Settings \u2192 **Tools & Integrations** \u2192 **MCP Tools**\n2. Click **\"+ New MCP Server\"**\n3. Configure with the same details as the JSON method above\n\n**Note:** Replace the paths with your actual project directory paths and API credentials.\n\n</details>\n\n<details>\n<summary><b>VS Code Usage</b></summary>\n\n### VS Code Usage\n\nTo use Alpaca MCP Server with VS Code, please follow the steps below.\n\nVS Code supports MCP servers through GitHub Copilot's agent mode.\nThe official VS Code setup document is available here: https://code.visualstudio.com/docs/copilot/chat/mcp-servers\n\n**Prerequisites**\n- VS Code with GitHub Copilot extension installed and active subscription\n- Python and virtual environment set up (follow Installation steps above)\n- MCP support enabled in VS Code (see below)\n\n#### 1. Enable MCP Support in VS Code\n\n1. Open VS Code Settings (Ctrl/Cmd + ,)\n2. Search for \"chat.mcp.enabled\" to check the box to enable MCP support\n3. Search for \"github.copilot.chat.experimental.mcp\" to check the box to use instruction files\n\n#### 2. Configure the MCP Server\n\n**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.\n\n**For workspace-specific settings:**\n\n1. Create `.vscode/mcp.json` in your project root.\n2. Add the Alpaca MCP server configuration manually to the mcp.json file:\n\n For Linux/macOS:\n ```json\n {\n \"mcp\": {\n \"servers\": {\n \"alpaca\": {\n \"type\": \"stdio\",\n \"command\": \"bash\",\n \"args\": [\"-c\", \"cd ${workspaceFolder} && source ./venv/bin/activate && python alpaca_mcp_server.py\"],\n \"env\": {\n \"ALPACA_API_KEY\": \"your_alpaca_api_key\",\n \"ALPACA_SECRET_KEY\": \"your_alpaca_secret_key\"\n }\n }\n }\n }\n }\n ```\n\n For Windows:\n ```json\n {\n \"mcp\": {\n \"servers\": {\n \"alpaca\": {\n \"type\": \"stdio\", \n \"command\": \"cmd\",\n \"args\": [\"/c\", \"cd /d ${workspaceFolder} && .\\\\venv\\\\Scripts\\\\activate && python alpaca_mcp_server.py\"],\n \"env\": {\n \"ALPACA_API_KEY\": \"your_alpaca_api_key\",\n \"ALPACA_SECRET_KEY\": \"your_alpaca_secret_key\"\n }\n }\n }\n }\n }\n ```\n **Note:** Replace `${workspaceFolder}` with your actual project path. For example:\n - Linux/macOS: `/Users/username/Documents/alpaca-mcp-server`\n - Windows: `C:\\\\Users\\\\username\\\\Documents\\\\alpaca-mcp-server`\n \n\n**For user-wide settings:**\n\nTo 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.\nSpecify the server in the `mcp` VS Code user settings (`settings.json`) to enable the MCP server across all workspaces.\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"alpaca\": {\n \"type\": \"stdio\",\n \"command\": \"bash\",\n \"args\": [\"-c\", \"cd ${workspaceFolder} && source ./venv/bin/activate && python alpaca_mcp_server.py\"],\n \"env\": {\n \"ALPACA_API_KEY\": \"your_alpaca_api_key\",\n \"ALPACA_SECRET_KEY\": \"your_alpaca_secret_key\"\n }\n }\n }\n }\n}\n```\n\n</details>\n\n<details>\n<summary><b>PyCharm Usage</b></summary>\n\n### PyCharm Usage\n\nTo 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\n\nPyCharm supports MCP servers through its integrated MCP client functionality. This configuration ensures proper logging behavior and prevents common startup issues.\n\n1. **Open PyCharm Settings**\n - Go to `File \u2192 Settings`\n - Navigate to `Tools \u2192 Model Context Protocol (MCP)` (or similar location depending on PyCharm version)\n\n2. **Add New MCP Server**\n - Click `Add` or `+` to create a new server configuration. You can also import the settings from Claude by clicking the corresponding button.\n - **Name**: Enter any name you prefer for this server configuration (e.g., Alpaca MCP).\n - **Command**: \"/path/to/your/alpaca-mcp-server/venv/bin/python\"\n - **Arguments**: \"alpaca_mcp_server.py\"\n - **Working directory**: \"/path/to/your/alpaca-mcp-server\"\n\n3. **Set Environment Variables**\n Add the following environment variables in the Environment Variables parameter:\n ```\n ALPACA_API_KEY=\"your_alpaca_api_key\"\n ALPACA_SECRET_KEY=\"your_alpaca_secret_key\"\n MCP_CLIENT=pycharm\n ```\n\n</details>\n\n<details>\n<summary><b>Docker Usage</b></summary>\n\n### Docker Usage\n\nTo use Alpaca MCP Server with Docker, please follow the steps below.\n\n**Prerequisite:** \nYou must have [Docker installed](https://docs.docker.com/get-docker/) on your system.\n\n#### Build and run locally (recommended)\n```bash\ndocker build -t alpaca-mcp-server .\ndocker run -it --rm \\\n -e ALPACA_API_KEY=your_alpaca_api_key \\\n -e ALPACA_SECRET_KEY=your_alpaca_secret_key \\\n alpaca-mcp-server\n```\nThis builds and runs the server from your local source code.\n\n#### HTTP mode example\n```bash\ndocker run --rm -p 8000:8000 alpaca-mcp-server --transport http\n```\n\n#### Alternative: Use published image (if available)\n```bash\ndocker run --pull=always -it --rm \\\n -e ALPACA_API_KEY=your_alpaca_api_key \\\n -e ALPACA_SECRET_KEY=your_alpaca_secret_key \\\n ghcr.io/alpacahq/alpaca-mcp-server:latest\n```\n**Note:** Verify the published image exists and is maintained before using.\n\n\n#### Using with Claude Desktop\n```json\n{\n \"mcpServers\": {\n \"alpaca\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\",\n \"--rm\",\n \"-e\", \"ALPACA_API_KEY\",\n \"-e\", \"ALPACA_SECRET_KEY\",\n \"alpaca-mcp-server\"\n ],\n \"env\": {\n \"ALPACA_API_KEY\": \"your_alpaca_api_key\",\n \"ALPACA_SECRET_KEY\": \"your_alpaca_secret_key\"\n }\n }\n }\n}\n```\nProvide values via the MCP client's env block, and use -e VAR flags to forward them into the Docker container. Avoid hardcoding secrets directly in args.\n\n#### Alternative credential methods\n```bash\n# Using an env file\ndocker run --env-file .env alpaca-mcp-server\n\n# Bind mounting a .env file\ndocker run -v $(pwd)/.env:/app/.env:ro alpaca-mcp-server\n```\n\n**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.\n\n**For more advanced Docker usage:** See the [official Docker documentation](https://docs.docker.com/).\n\n</details>\n\n## HTTP Transport for Remote Usage\n\n<details>\n<summary><b>Expand for Remote Server Setup Instructions</b></summary>\n\nFor 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:\n\n### Server Setup (Remote Machine)\n```bash\n# Start server with HTTP transport (default: 127.0.0.1:8000)\npython alpaca_mcp_server.py --transport http\n\n# Start server with custom host/port for remote access\npython alpaca_mcp_server.py --transport http --host 0.0.0.0 --port 9000\n\n# For systemd service (example from GitHub issue #6)\n# Update your start script to use HTTP transport\n#!/bin/bash\ncd /root/alpaca-mcp-server\nsource venv/bin/activate\nexec python3 -u alpaca_mcp_server.py --transport http --host 0.0.0.0 --port 8000\n```\n\n**Remote Access Options:**\n1. **Direct binding**: Use `--host 0.0.0.0` to bind to all interfaces for direct remote access\n2. **SSH tunneling**: `ssh -L 8000:localhost:8000 user@your-server` for secure access (recommended for localhost binding)\n3. **Reverse proxy**: Use nginx/Apache to expose the service securely with authentication\n\n### Client Setup\nUpdate your Claude Desktop configuration to use HTTP:\n```json\n{\n \"mcpServers\": {\n \"alpaca\": {\n \"transport\": \"http\",\n \"url\": \"http://your-server-ip:8000/mcp\",\n \"env\": {\n \"ALPACA_API_KEY\": \"your_alpaca_api_key\",\n \"ALPACA_SECRET_KEY\": \"your_alpaca_secret_key\"\n }\n }\n }\n}\n```\n\n### Troubleshooting HTTP Transport Issues\n- **Port not listening**: Ensure the server started successfully and check firewall settings\n- **Connection refused**: Verify the server is running on the expected host:port\n- **ENOENT errors**: Make sure you're using the updated server command with `--transport http`\n- **Remote access**: Use `--host 0.0.0.0` for direct access, or SSH tunneling for localhost binding\n- **Port conflicts**: Use `--port <PORT>` to specify a different port if default is busy\n\n</details>\n\n## Available Tools\n\n<details>\n<summary><b>View All Available Tools</b></summary>\n\n### Account & Positions\n\n* `get_account_info()` \u2013 View balance, margin, and account status\n* `get_positions()` \u2013 List all held assets\n* `get_open_position(symbol)` \u2013 Detailed info on a specific position\n* `close_position(symbol, qty|percentage)` \u2013 Close part or all of a position\n* `close_all_positions(cancel_orders)` \u2013 Liquidate entire portfolio\n\n### Stock Market Data\n\n* `get_stock_quote(symbol)` \u2013 Real-time bid/ask quote\n* `get_stock_bars(symbol, days=5, timeframe=\"1Day\", limit=None, start=None, end=None)` \u2013 OHLCV historical bars with flexible timeframes (1Min, 5Min, 1Hour, 1Day, etc.)\n* `get_stock_latest_trade(symbol, feed=None, currency=None)` \u2013 Latest market trade price\n* `get_stock_latest_bar(symbol, feed=None, currency=None)` \u2013 Most recent OHLC bar\n* `get_stock_snapshot(symbol_or_symbols, feed=None, currency=None)` \u2013 Comprehensive snapshot with latest quote, trade, minute bar, daily bar, and previous daily bar\n* `get_stock_trades(symbol, days=5, limit=None, sort=Sort.ASC, feed=None, currency=None, asof=None)` \u2013 Trade-level history\n\n### Orders\n\n* `get_orders(status, limit)` \u2013 Retrieve all or filtered orders\n* `place_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)` \u2013 Place a stock order of any type (market, limit, stop, stop_limit, trailing_stop)\n* `cancel_order_by_id(order_id)` \u2013 Cancel a specific order\n* `cancel_all_orders()` \u2013 Cancel all open orders\n\n### Crypto\n\n* `place_crypto_order(symbol, side, order_type=\"market\", time_in_force=\"gtc\", qty=None, notional=None, limit_price=None, stop_price=None, client_order_id=None)` \u2013 Place a crypto order supporting market, limit, and stop_limit types with GTC/IOC time in force\n\n### Options\n\n* `get_option_contracts(underlying_symbol, expiration_date=None, expiration_date_gte=None, expiration_date_lte=None, expiration_expression=None, strike_price_gte=None, strike_price_lte=None, type=None, status=None, root_symbol=None, limit=None)` \u2013 \u2013 Get option contracts with flexible filtering.\n* `get_option_latest_quote(option_symbol)` \u2013 Latest bid/ask on contract\n* `get_option_snapshot(symbol_or_symbols)` \u2013 Get Greeks and underlying\n* `place_option_market_order(legs, order_class=None, quantity=1, time_in_force=TimeInForce.DAY, extended_hours=False)` \u2013 Execute option strategy\n* `exercise_options_position(symbol_or_contract_id)` \u2013 Exercise a held option contract, converting it into the underlying asset\n\n### Market Info & Corporate Actions\n\n* `get_market_clock()` \u2013 Market open/close schedule\n* `get_market_calendar(start, end)` \u2013 Holidays and trading days\n* `get_corporate_announcements(ca_types, start, end, symbols)` \u2013 Historical and future corporate actions (e.g., earnings, dividends, splits)\n\n### Watchlists\n\n* `create_watchlist(name, symbols)` \u2013 Create a new list\n* `update_watchlist(watchlist_id, name=None, symbols=None)` \u2013 Modify an existing list\n* `get_watchlists()` \u2013 Retrieve all saved watchlists\n\n### Assets\n\n* `get_asset_info(symbol)` \u2013 Search asset metadata\n* `get_all_assets(status=None, asset_class=None, exchange=None, attributes=None)` \u2013 List all tradable instruments with filtering options\n\n</details>\n\n## Security Notice\n\nThis 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.\n\n**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.\n\n## Usage Analytics Notice\n\nThe 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' \u2014 though we kindly hope you'll keep it enabled to support ongoing improvements.\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details\n\n\n## Disclosure\nPlease note that the content on this page is for informational purposes only. Alpaca does not recommend any specific securities or investment strategies.\n\nOptions 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](https://www.theocc.com/company-information/documents-and-archives/options-disclosure-document?ref=alpaca.markets)) before investing in options.\n\n\nAlpaca 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.\n\nAll 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.\n\nThe algorithm\u2019s 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.\n\nPast hypothetical backtest results do not guarantee future returns, and actual results may vary from the analysis.\n\nThe 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, \u201cAlpaca\u201d) is not authorized to do business.\n\nSecurities brokerage services are provided by Alpaca Securities LLC (\"Alpaca Securities\"), member [FINRA](https://www.finra.org/)/[SIPC](https://www.sipc.org/), a wholly-owned subsidiary of AlpacaDB, Inc. Technology and services are offered by AlpacaDB, Inc.\n\nThis 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.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Alpaca Trading API integration for Model Context Protocol (MCP)",
"version": "1.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/alpacahq/alpaca-mcp-server/issues",
"Documentation": "https://github.com/alpacahq/alpaca-mcp-server#readme",
"Homepage": "https://alpaca.markets/",
"Repository": "https://github.com/alpacahq/alpaca-mcp-server"
},
"split_keywords": [
"ai",
" alpaca",
" finance",
" llm",
" mcp",
" model-context-protocol",
" trading"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7160e0420cbe6957656722e6eb434d69b77b83111a0b8e6ee0551f9770232d89",
"md5": "50681315326814f5dd787a925384d73e",
"sha256": "59bfacb16c822ee880fcd4058ae72a1687a3970d3c69406bc803bd06b03c31eb"
},
"downloads": -1,
"filename": "alpaca_mcp_server-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "50681315326814f5dd787a925384d73e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 44108,
"upload_time": "2025-10-06T23:39:53",
"upload_time_iso_8601": "2025-10-06T23:39:53.241142Z",
"url": "https://files.pythonhosted.org/packages/71/60/e0420cbe6957656722e6eb434d69b77b83111a0b8e6ee0551f9770232d89/alpaca_mcp_server-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6ea33653499263602722a1ccd3bec3e39127384a2d592a2eff42e8bbce1a2fe8",
"md5": "a10a3b6f45d890e9c95becb31716cc28",
"sha256": "7c78d928949c69d9dfd2b43c2302b7156be0c9a600c7e20b500756d7b90a6f3f"
},
"downloads": -1,
"filename": "alpaca_mcp_server-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "a10a3b6f45d890e9c95becb31716cc28",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 104049,
"upload_time": "2025-10-06T23:39:54",
"upload_time_iso_8601": "2025-10-06T23:39:54.662435Z",
"url": "https://files.pythonhosted.org/packages/6e/a3/3653499263602722a1ccd3bec3e39127384a2d592a2eff42e8bbce1a2fe8/alpaca_mcp_server-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 23:39:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alpacahq",
"github_project": "alpaca-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "alpaca-py",
"specs": []
},
{
"name": "mcp",
"specs": []
},
{
"name": "python-dotenv",
"specs": []
}
],
"lcname": "alpaca-mcp-server"
}
JSON
