alpaca-mcp-server

Translates conversational natural language requests into structured Alpaca API calls through a FastMCP-based protocol bridge. The server implements a request processing pipeline that parses LLM-generated text, maps it to 44+ registered tools, and executes corresponding Alpaca API operations with automatic parameter extraction and type coercion. This enables users to execute complex trading operations (orders, position management, data queries) by describing intent in plain English without learning API syntax.

Provides environment-variable-controlled switching between paper trading (PAPER=True, default) and live trading (PAPER=False) modes that route all TradingClient operations to separate Alpaca API endpoints with distinct credential sets. The server initializes the appropriate API endpoint URL and authentication context at startup based on the PAPER flag, ensuring all subsequent order and position operations target the correct trading environment without code changes. This enables safe testing and development before risking real capital.

Supports flexible credential and configuration management through multiple sources: .env files in the project directory, environment variables, and Claude Desktop config (claude_desktop_config.json). The server reads configuration at startup and initializes API clients with the appropriate credentials and endpoints. Supported configuration variables include ALPACA_API_KEY, ALPACA_SECRET_KEY, PAPER (trading mode), and optional proxy settings. This enables users to configure the server without modifying code and supports multiple deployment scenarios (local, Docker, cloud).

Provides a Dockerfile and Docker Compose configuration for containerizing the MCP server and deploying it in isolated environments. The Docker setup installs Python 3.10+, dependencies from requirements.txt, and runs the server as a container process. Docker environment variables can be passed at runtime to configure API credentials and trading mode. This enables deployment to cloud platforms (AWS, GCP, Azure), Kubernetes clusters, or local Docker environments without manual Python installation.

Implements MCP tool discovery and schema documentation through the FastMCP framework, which automatically generates JSON schemas for all 44+ registered tools. Each tool includes a name, description, input schema (parameters with types and constraints), and output schema. MCP clients (Claude Desktop, Cursor, VSCode) use these schemas to discover available tools, validate parameters, and provide autocomplete suggestions. The server exposes tool metadata through the MCP protocol's tools/list and tools/describe endpoints.

Exposes Alpaca TradingClient methods as MCP tools for querying and managing account state, including account details (cash, buying power, equity), position tracking (open positions, P&L, Greeks for options), and portfolio metrics. Each tool wraps a specific TradingClient method (e.g., get_account(), get_positions(), get_position(symbol)) and returns structured data formatted for LLM consumption. The server maintains no local state; all queries hit the live Alpaca API, ensuring real-time accuracy.

Provides access to Alpaca's StockHistoricalDataClient for querying historical market data, including bars (OHLCV candles), quotes (bid/ask spreads), and latest prices across multiple timeframes (minute, hour, day, week, month). Tools accept symbol(s), date ranges, and timeframe parameters, returning structured arrays of price data suitable for technical analysis, backtesting, and strategy validation. The server supports batch queries for multiple symbols in a single request, reducing round-trips.

Exposes Alpaca TradingClient order methods as MCP tools for creating, modifying, and canceling orders across stocks, ETFs, crypto, and options. Tools support multiple order types (market, limit, stop, stop-limit, trailing-stop) and time-in-force options (day, gtc, opg, cls). The server translates natural language order descriptions (e.g., 'buy 100 shares of AAPL at market') into structured order objects with proper parameter validation, then submits to Alpaca's order execution engine. All orders are subject to account buying power and position limits.

Integrates Alpaca's OptionHistoricalDataClient to provide options-specific tools for querying option contracts, retrieving Greeks (delta, gamma, theta, vega, rho), and analyzing options chains. Tools support filtering by symbol, expiration date, strike price, and option type (call/put), returning structured contract data with computed Greeks. The server also exposes options order placement through the TradingClient, enabling buy-to-open, sell-to-close, and spread strategies. Greeks are computed by Alpaca's pricing model and updated in real-time.

Provides access to Alpaca's StockDataStream for real-time market data feeds including trades, quotes, and bars. The server initializes a WebSocket connection to Alpaca's data stream endpoint and exposes tools for subscribing to specific symbols and data types. Streamed data is buffered and made available to LLM clients through polling or callback mechanisms. This enables trading agents to react to live market events without polling the REST API repeatedly.

Exposes Alpaca TradingClient methods for creating, updating, and querying watchlists, as well as querying asset information (symbols, asset classes, tradability status). Tools allow users to organize symbols into named watchlists for portfolio tracking and strategy management. Asset queries return metadata including exchange, asset class (stock, etf, crypto, option), and trading status (active, inactive, delisted). This enables LLM agents to build dynamic watchlists and validate symbols before trading.

Provides tools for querying corporate actions (dividends, splits, mergers) and market information (trading calendar, market status, holidays). Tools return structured data about upcoming and historical corporate actions, enabling trading agents to adjust positions before ex-dividend dates or stock splits. Market calendar queries return trading hours and holiday schedules, allowing agents to schedule orders appropriately. This information is sourced from Alpaca's market data providers and updated in real-time.

Implements the FastMCP framework to handle Model Context Protocol server initialization, tool registration, and request routing. The server starts as a standalone process (via python alpaca_mcp_server.py) or within a Docker container, initializes all Alpaca API clients based on environment configuration, registers 44+ tools with the MCP protocol, and listens for incoming tool calls from MCP clients (Claude Desktop, Cursor, VSCode). The server maintains a single persistent connection per client and routes all requests through the appropriate Alpaca API client.