Alpaca MCP Server
A Model Context Protocol (MCP) server for Alpaca Trading API that provides seamless integration with AI assistants and development tools.
✅ Compatibility
Tested and verified to work on Apple Silicon M1 Pro laptops running macOS.
Features
- Account Information: Get real-time account details, buying power, equity, and status
- Portfolio Management: View current positions with P&L tracking
- Market Data: Retrieve real-time stock quotes with bid/ask spreads
- Order Management: List and monitor recent orders
- Paper Trading Support: Safe testing environment with paper trading API
- Live Trading Ready: Compatible with live trading (use with caution)
Installation
Prerequisites
pip install alpaca-trade-api
Quick Start
- Clone the repository:
git clone https://github.com/jwaresolutions/alpaca-mcp-server.git
cd alpaca-mcp-server
- Set up your Alpaca API credentials:
Create environment variables or add to your shell profile:
export APCA_API_KEY_ID="your_api_key_here"
export APCA_API_SECRET_KEY="your_secret_key_here"
export APCA_API_BASE_URL="https://paper-api.alpaca.markets" # Paper trading
# export APCA_API_BASE_URL="https://api.alpaca.markets" # Live trading
- Test the server:
python alpaca_mcp_server.py
MCP Integration
For Cline/Claude Dev Tools
Add to your MCP settings JSON:
{
"mcpServers": {
"alpaca": {
"command": "python",
"args": ["/path/to/alpaca-mcp-server/alpaca_mcp_server.py"],
"env": {
"APCA_API_KEY_ID": "your_api_key_here",
"APCA_API_SECRET_KEY": "your_secret_key_here",
"APCA_API_BASE_URL": "https://paper-api.alpaca.markets"
}
}
}
}
For Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"alpaca": {
"command": "python",
"args": ["/path/to/alpaca-mcp-server/alpaca_mcp_server.py"],
"env": {
"APCA_API_KEY_ID": "your_api_key_here",
"APCA_API_SECRET_KEY": "your_secret_key_here",
"APCA_API_BASE_URL": "https://paper-api.alpaca.markets"
}
}
}
}
Available Tools
1. get_account
Get comprehensive account information including:
- Account status and number
- Buying power and cash available
- Portfolio equity and value
- Pattern day trader status
- Day trade count
- SMA (Special Memorandum Account)
2. get_positions
View current stock positions with:
- Symbol and quantity
- Current market value
- Cost basis and P&L
- Unrealized gains/losses
- Current stock price
- Position side (long/short)
3. get_quote
Get real-time market quotes for any symbol:
- Bid and ask prices
- Bid and ask sizes
- Price spread calculation
- Timestamp of quote
Parameters:
symbol(required): Stock symbol (e.g., "AAPL", "TSLA", "NVDA")
4. get_orders
List recent orders with filtering:
- Order ID and status
- Symbol and quantity
- Order type and side
- Fill information
- Submission timestamps
Parameters:
status(optional): "open", "closed", or "all" (default: "all")limit(optional): Maximum number of orders (default: 10)
API Credentials
Getting Alpaca API Keys
- Sign up at Alpaca Markets
- Go to the dashboard and navigate to "API Keys"
- Generate new API keys for paper trading or live trading
- Copy your API Key ID and Secret Key
Environment Setup
Option 1: Environment Variables
export APCA_API_KEY_ID="PK..."
export APCA_API_SECRET_KEY="..."
export APCA_API_BASE_URL="https://paper-api.alpaca.markets"
Option 2: .env file
APCA_API_KEY_ID=PK...
APCA_API_SECRET_KEY=...
APCA_API_BASE_URL=https://paper-api.alpaca.markets
Safety and Paper Trading
⚠️ Important: This server defaults to paper trading mode for safety. Paper trading uses virtual money and is perfect for testing and development.
To switch to live trading, change the base URL to:
APCA_API_BASE_URL=https://api.alpaca.markets
Use live trading only when you're confident in your setup and ready to trade with real money.
Troubleshooting
Common Issues
-
"Missing API credentials" error:
- Ensure environment variables are set correctly
- Check that variable names match exactly:
APCA_API_KEY_ID,APCA_API_SECRET_KEY
-
"Connection failed" error:
- Verify your API keys are valid
- Check your internet connection
- Ensure you're using the correct base URL for paper/live trading
-
"Module not found" error:
- Install required dependencies:
pip install alpaca-trade-api
- Install required dependencies:
Testing the Server
You can test the server manually using JSON-RPC:
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | python alpaca_mcp_server.py
Expected response should include available tools.
Development
Project Structure
alpaca-mcp-server/
├── alpaca_mcp_server.py # Main MCP server
├── README.md # This documentation
├── requirements.txt # Python dependencies
└── examples/ # Usage examples
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Test thoroughly with paper trading
- Submit a pull request
License
MIT License - see LICENSE file for details.
Support
- Issues: GitHub Issues
- Alpaca API Docs: Alpaca Markets API
- MCP Protocol: Model Context Protocol
Disclaimer
This software is for educational and development purposes. When using live trading features, you are trading with real money. Always test thoroughly with paper trading first. The authors are not responsible for any financial losses.