Alpaca’s MCP Server v2 is a thorough rewrite of their official Model Context Protocol server, designed to expose Alpaca’s Trading API to any MCP-compatible AI client. Unlike the previous version, this iteration switches to spec-derived tool generation based on OpenAPI, moving away from handcrafted tools. The result is a cleaner, more maintainable server that supports stocks, options, crypto, portfolio management, and market data endpoints via MCP tools.
how alpaca-mcp-server v2 exposes trading APIs through MCP
At its core, Alpaca MCP Server v2 acts as a bridge between Alpaca’s comprehensive Trading API and AI agents that understand the Model Context Protocol. It uses FastMCP, a Python framework optimized for MCP servers, and derives its tool definitions directly from Alpaca’s OpenAPI specifications. This approach ensures the tools stay aligned with the underlying API without manual intervention.
The server supports various asset classes — stocks, options, cryptocurrencies — and features like portfolio management and market data access. It exposes these capabilities as MCP tools that any compatible client, such as Claude Desktop, Cursor, VS Code, Claude Code, or Gemini CLI, can consume.
The architecture is Python-based, requiring Python 3.10+ and the uv runtime for async capabilities. The server can run standalone with uvx or within a Docker container, although the README focuses on local execution. Configuration is handled entirely via environment variables within the MCP client config, avoiding .env files or initialization commands, which streamlines deployment and updates.
A notable feature is the server-side filtering of toolsets controlled by the ALPACA_TOOLSETS environment variable. This pattern scopes which API subsets are exposed to clients, a useful technique in agentic workflows where capability control is critical. Paper trading and live trading modes are toggled via ALPACA_PAPER_TRADE, simplifying switching between testing and production environments.
spec-derived tools and environment variable configuration as technical strengths
The shift from manually crafted MCP tools in V1 to OpenAPI spec-derived tooling in V2 is a clear architectural improvement. It reduces the risk of drift between the API surface and the MCP toolset, making maintenance easier as Alpaca updates their APIs. This approach also enforces consistency in tool naming and parameters, though it comes at the cost of breaking backward compatibility. Users migrating from V1 will need to update their client configurations and cached tool lists accordingly.
The environment variable-based configuration in MCP client setups is another strength. It consolidates credentials and settings into a single place per client, improving security and simplifying management. Eliminating .env files or separate init commands reduces friction in onboarding and deployment.
The ALPACA_TOOLSETS filtering mechanism is a clean, explicit pattern for controlling exposed functionality. In agentic systems where you want to restrict or tailor capabilities, having server-side filtering avoids cluttering clients with unnecessary tools and enforces policy boundaries efficiently.
That said, the tradeoff of breaking backward compatibility is non-trivial. It means existing workflows and custom prompts relying on V1 tool names or parameters will break and require rework. This is justified by the cleaner, more robust design but is an important consideration for production users.
The codebase itself is Pythonic and clean, relying heavily on FastMCP and OpenAPI tooling. This reduces boilerplate and improves DX for maintainers.
quick start with alpaca-mcp-server v2
The README provides clear instructions for adding the server to various popular MCP clients. The key concept is to embed the server command and environment variables directly into the client’s MCP server configuration, then restart the client. No additional init commands or .env files are needed.
Here are examples for different clients:
Claude Desktop
Edit the JSON config file for Claude Desktop to add the Alpaca MCP server with environment variables:
{
"mcpServers": {
"alpaca": {
"command": "uvx",
"args": ["alpaca-mcp-server"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
Cursor
Add the server to Cursor’s MCP config file:
{
"mcpServers": {
"alpaca": {
"command": "uvx",
"args": ["alpaca-mcp-server"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
VS Code
Create .vscode/mcp.json in your project root and configure:
{
"mcp": {
"servers": {
"alpaca": {
"type": "stdio",
"command": "uvx",
"args": ["alpaca-mcp-server"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
}
PyCharm
From PyCharm settings (File → Settings → Tools → Model Context Protocol (MCP)):
- Add a new server:
- Type: stdio
- Command: uvx
- Arguments: alpaca-mcp-server
- Set environment variables:
ALPACA_API_KEY=your_alpaca_api_key
ALPACA_SECRET_KEY=your_alpaca_secret_key
Claude Code
Add the server via the CLI:
claude mcp add alpaca --scope user --transport stdio uvx alpaca-mcp-server \
--env ALPACA_API_KEY=your_alpaca_api_key \
--env ALPACA_SECRET_KEY=your_alpaca_secret_key
This streamlined setup highlights the DX focus in V2 — all credentials and config are centralized within the client config, making it easy to manage multiple MCP servers or switch environments.
who should consider alpaca-mcp-server v2
Alpaca MCP Server v2 is relevant if you’re building AI agent workflows that need programmatic access to Alpaca’s diverse trading APIs through a standardized RPC model. It fits well when using MCP-compatible clients like Claude Desktop or Cursor to enable conversational or autonomous trading tasks.
The server’s spec-driven design reduces maintenance overhead and keeps the MCP tools in sync with Alpaca’s API evolution. The environment variable config offers a clean deployment pattern.
However, the breaking changes from V1 mean existing users should plan migration carefully, updating client configs, cached tools, and any custom prompts or automation depending on tool names and parameters.
If your use case demands stable backward compatibility or you rely heavily on V1 workflows, this might introduce friction. But for new projects or those willing to adapt, V2’s improvements in consistency, maintainability, and capability scoping make it a solid choice.
Overall, Alpaca MCP Server v2 is a pragmatic, well-structured bridge between Alpaca’s trading API and modern AI agent ecosystems built on MCP. It shows how spec-driven tool generation and environment-variable-driven config can improve DX and operational clarity, even if it requires a migration reset.
→ GitHub Repo: alpacahq/alpaca-mcp-server ⭐ 698 · Python