alpaca

The Alpaca MCP Server exposes Alpaca's trading API through the Model Context Protocol, enabling natural language trading capabilities via AI assistants such as Claude Desktop, Cursor, and VS Code. It supports trading across assets (stocks, options, and crypto), portfolio management, and real-time market data. Once running, you can connect your MCP client to the alpaca MCP server instance using the provided mcp.json configuration. Use the included tools to place orders, query account status, fetch market data, and manage risk with natural language prompts. The server relies on your Alpaca API credentials to perform live or paper trading as configured in your environment variables and client configuration.

Prerequisites:

• Python 3.10+
• uv (installation guidance at https://docs.astral.sh/uv/getting-started/installation/)
• Alpaca Trading API keys (paper trading available)
• MCP client (Claude Desktop, Cursor, VS Code, etc.)

Step 1: Install uvx (one-time)

• Install uv/uvx per your platform following the official guide

Step 2: Install the Alpaca MCP Server (local installation)

• Option A: One-click via uvx (recommended for quick start)
  • uvx alpaca-mcp-server init

Step 3: Configure API keys

• Set your Alpaca API keys in your environment or a .env file used by the MCP server:
  • ALPACA_API_KEY=your_alpaca_api_key
  • ALPACA_SECRET_KEY=your_alpaca_secret_key

Step 4: Run the MCP server

• Start the server with uvx using the embedded config example:
  • uvx alpaca-mcp-server serve

Step 5: Configure MCP client

• Add the Alpaca MCP server to your MCP client configuration (Claude Desktop, Cursor, etc.) with the following example: { "mcpServers": { "alpaca": { "command": "uvx", "args": ["alpaca-mcp-server", "serve"], "env": { "ALPACA_API_KEY": "your_alpaca_api_key", "ALPACA_SECRET_KEY": "your_alpaca_secret_key" } } } }

Optional: If you prefer a local Python-based run, ensure Python 3.10+ is installed and run the server using your preferred Python workflow after cloning the repository and installing dependencies as needed.

Tips and common issues:

• Ensure your Alpaca API keys have the appropriate permissions for the actions you want to perform (trading vs data access).
• If you encounter environment variable issues, verify that your MCP client config takes precedence following the client’s docs.
• When switching from paper to live trading, update TRADE_API_URL/STREAM_DATA_WSS and related env values in your .env and client config as needed.
• If uvx is not recognized in your shell, restart your terminal or add uvx to your PATH.
• For troubleshooting, check the MCP server logs for authentication errors, invalid keys, or network connectivity problems with Alpaca services.