Alpaca MCP Server

# 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 ```bash pip install alpaca-trade-api ``` ### Quick Start 1. **Clone the repository:** ```bash git clone https://github.com/jwaresolutions/alpaca-mcp-server.git cd alpaca-mcp-server ``` 2. **Set up your Alpaca API credentials:** Create environment variables or add to your shell profile: ```bash 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 ``` 3. **Test the server:** ```bash python alpaca_mcp_server.py ``` ## MCP Integration ### For Cline/Claude Dev Tools Add to your MCP settings JSON: ```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`: ```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 1. Sign up at [Alpaca Markets](https://alpaca.markets/) 2. Go to the dashboard and navigate to "API Keys" 3. Generate new API keys for paper trading or live trading 4. Copy your API Key ID and Secret Key ### Environment Setup **Option 1: Environment Variables** ```bash 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** ```bash 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: ```bash 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 1. **"Missing API credentials" error:** - Ensure environment variables are set correctly - Check that variable names match exactly: `APCA_API_KEY_ID`, `APCA_API_SECRET_KEY` 2. **"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 3. **"Module not found" error:** - Install required dependencies: `pip install alpaca-trade-api` ### Testing the Server You can test the server manually using JSON-RPC: ```bash 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 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Test thoroughly with paper trading 5. Submit a pull request ## License MIT License - see LICENSE file for details. ## Support - **Issues**: [GitHub Issues](https://github.com/jwaresolutions/alpaca-mcp-server/issues) - **Alpaca API Docs**: [Alpaca Markets API](https://alpaca.markets/docs/) - **MCP Protocol**: [Model Context Protocol](https://modelcontextprotocol.io/) ## 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.