alpaca-mcp-server

<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

• Prerequisites
• Start here
• Getting Your API Keys
• Switching API Keys for Live Trading
• Quick Local Installation for MCP Server
• Features
• Example Prompts
• Example Outputs
• Available Tools
• MCP Client Configuration
• OAuth Bearer Token Support
• HTTP Transport for Remote Usage
• Disclosure

Prerequisites

You need the following prerequisites to configure and run the Alpaca MCP Server.

• Terminal (macOS/Linux) | Command Prompt or PowerShell (Windows)
• Python 3.10+ (Check the official installation guide and confirm the version by typing the following command: python3 --version in Terminal)
• uv (Install using the official guide)
  Tip: uv can be installed either through a package manager (like Homebrew) or directly using curl | sh.
• Alpaca Trading API keys (free paper trading account available)
• MCP client (Claude Desktop, Cursor, VS Code, etc.)

Note: Using an MCP server requires installation and configuration of both the MCP server and MCP client.

Start here

Note: These steps assume all Prerequisites have been installed.

• Claude Desktop
  • Local: Use uvx or install.py see Claude Desktop Configuration
• Claude Mobile
  • Remote Hosting: Deploy to cloud service see Claude Mobile Configuration
• ChatGPT
  • Remote Hosting: Deploy to cloud service see ChatGPT Configuration
• Cursor
  • Local (Cursor Directory): Use the Cursor Directory entry and connect in a few clicks see Cursor Configuration
  • Local (install.py): Use install.py to set up and auto-configure Cursor see Cursor Configuration
• VS Code
  • Local: Use uvx see VS Code Configuration
• PyCharm
  • Local: Use uvx see PyCharm Configuration
• Claude Code
  • Local: Use uvx or Docker see Claude Code Configuration
• Gemini CLI
  • Local: Use uvx see Gemini CLI Configuration

Note: How to show hidden files

• macOS Finder: Command + Shift + .
• Linux file managers: Ctrl + H
• Windows File Explorer: Alt, V, H
• Terminal (macOS/Linux): ls -a

Getting Your API Keys

1. Visit Alpaca Trading API Account Dashboard
2. Create a free paper trading account
3. Generate API keys from the dashboard

Switching API Keys for Live Trading

To enable live trading with real funds or switch between different accounts, 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.

<details> <summary><b>Step 1: Update MCP Server Config .env file</b></summary>

Method 1: Run the init command again to update your .env file

# Follow the prompts to update your keys and toggle paper/live trading
uvx alpaca-mcp-server init

Method 2: Manually Update

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

</details> <details> <summary><b>Step 2: Update MCP Client Config Json file</b></summary>

Step 2-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-2: Update the API keys in the env section:

F…