jwaresolutions/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

pip install alpaca-trade-api

Quick Start

1. Clone the repository:

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:

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:

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

1. Sign up at 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

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

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:

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
• 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.