DOCSEARCHbyAlgolia
Submit Docs

Alpaca MCP Server

repository·main·Indexed 21 days ago

https://github.com/alpacahq/alpaca-mcp-server

A Model Context Protocol (MCP) interface for Alpaca's Trading API (version 2.2.0). It enables AI assistants like Claude, Cursor, and VS Code to perform natural language trading operations, portfolio management, and market data retrieval for stocks, options, and crypto. The server supports both paper and live trading via environment variable configuration and provides a comprehensive set of tools for account management, order placement, and asset analysis.

Tokens
13.2K
Snippets
23
Records
43
Agent score
71%

What's inside alpaca-mcp-server

  1. Manage Alpaca MCP Server data collection and privacy

    main

    The Alpaca MCP server collects specific metadata for service improvement.

    • Collected Data: The user agent string 'ALPACA-MCP-SERVER' is sent with API calls.
    • Purpose: To identify MCP server usage and improve user experience.
    • Sharing: Data is not shared with third parties.
    • Opt-out: To opt-out of this collection, you must modify or remove the USER_AGENT constant in the source file .github/core/user_agent.py.

  2. Project structure of alpaca-mcp-server

    main

    The repository is organized as follows:

    • src/alpaca_mcp_server/: Core logic
      • cli.py: CLI entry point
      • server.py: FastMCP server built from OpenAPI specs
      • tool_registry.py: Tool names, descriptions, and risk classifications
      • toolsets.py: Toolset to operationId allowlists
      • overrides.py: Hand-crafted tools for complex trading endpoints
      • market_data_overrides.py: Hand-crafted tools for historical data
      • readme_docs.py: Read-only proxy tools for Alpaca ReadMe docs
      • specs/: OpenAPI specifications (trading-api.json, market-data-api.json)
    • tests/: Test suite including integrity, server construction, ReadMe, and Paper API integration tests.
    • scripts/: Utility scripts like sync-specs.sh to download latest OpenAPI specs.
    alpaca-mcp-server/
├── src/
│   └── alpaca_mcp_server/
│       ├── __init__.py
│       ├── cli.py            ← CLI entry point
│       ├── server.py         ← FastMCP server built from OpenAPI specs
│       ├── tool_registry.py  ← Tool names, descriptions, and output risk classifications
│       ├── toolsets.py       ← Toolset → operationId allowlists
│       ├── overrides.py      ← Hand-crafted tools for complex trading endpoints
│       ├── market_data_overrides.py ← Hand-crafted tools for historical data
│       ├── readme_docs.py    ← Read-only proxy tools for Alpaca ReadMe docs
│       └── specs/
│           ├── trading-api.json
│           └── market-data-api.json
├── tests/
│   ├── conftest.py           ← Shared fixtures and paper-account cleanup
│   ├── test_integrity.py     ← Spec ↔ toolset ↔ names consistency checks
│   ├── test_server_construction.py     ← Server build verification
│   ├── test_readme_integration.py     ← Live ReadMe docs MCP integration tests
│   └── test_paper_integration.py     ← Paper API integration tests
├── scripts/
│   └── sync-specs.sh        ← Download latest OpenAPI specs
├── .github/
│   └── workflows/
│       └── ci.yml            ← CI pipeline (core + integration)
├── AGENTS.md                 ← Instructions for coding agents
├── pyproject.toml
└── README.md

  3. Configure Alpaca MCP Server for VS Code

    main

    To use the server in VS Code, create a .vscode/mcp.json file in your project root.

    {
  "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"
        }
      }
    }
  }
}

  6. Configure Alpaca MCP Server for Claude Desktop

    main

    To use the Alpaca MCP server with Claude Desktop, edit your configuration file located at:

    • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    Add the alpaca server configuration under the mcpServers key. Credentials must be provided via the env object.

    {
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your_alpaca_api_key",
        "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
      }
    }
  }
}

  7. Configure Alpaca MCP Server for Claude Code CLI

    main

    Use the claude mcp add command to register the server. Replace the placeholders with your actual API keys.

    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

  8. Configure Alpaca MCP Server for PyCharm

    main
    1. Go to File → Settings → Tools → Model Context Protocol (MCP).
    2. Add a new server with the following settings:
      • Type: stdio
      • Command: uvx
      • Arguments: alpaca-mcp-server
    3. Set the following environment variables:
      • ALPACA_API_KEY=your_alpaca_api_key
      • ALPACA_SECRET_KEY=your_alpaca_secret_key

  9. Run the Alpaca MCP Server test suite

    main

    The project includes several test layers. You can run them locally using pytest.

    Core Tests

    Validates integrity and server construction without requiring network or credentials.

    pytest tests/test_integrity.py tests/test_server_construction.py -v

    Integration Tests

    Executes real calls against the Alpaca paper trading API. Requires ALPACA_API_KEY and ALPACA_SECRET_KEY.

    ALPACA_API_KEY=... ALPACA_SECRET_KEY=... pytest tests/ -m integration -v

    ReadMe Docs Integration Tests

    Executes live documentation lookup calls. Requires ALPACA_RUN_README_INTEGRATION=true.

    ALPACA_RUN_README_INTEGRATION=true pytest tests/test_readme_integration.py -v
    # Core tests (no credentials needed)
pytest tests/test_integrity.py tests/test_server_construction.py -v

# Integration tests (requires paper API keys)
ALPACA_API_KEY=... ALPACA_SECRET_KEY=... pytest tests/ -m integration -v

# ReadMe docs integration tests (requires network, no Alpaca credentials)
ALPACA_RUN_README_INTEGRATION=true pytest tests/test_readme_integration.py -v

  10. Build and Run Alpaca MCP Server with Docker

    main

    You can containerize the server using Docker. First, build the image, then add it to your MCP client configuration.

    # Build the image
git clone https://github.com/alpacahq/alpaca-mcp-server.git
cd alpaca-mcp-server
docker build -t mcp/alpaca:latest .

    MCP Client Configuration (Docker):

    {
  "mcpServers": {
    "alpaca": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ALPACA_API_KEY=your_key",
        "-e", "ALPACA_SECRET_KEY=your_secret",
        "-e", "ALPACA_PAPER_TRADE=true",
        "mcp/alpaca:latest"
      ]
    }
  }
}

  11. Filter enabled toolsets via ALPACA_TOOLSETS

    main

    By default, the server enables all available toolsets. To limit the server to a specific subset of tools, provide a comma-separated list to the ALPACA_TOOLSETS environment variable in your MCP client config.

    {
  "env": {
    "ALPACA_API_KEY": "...",
    "ALPACA_SECRET_KEY": "...",
    "ALPACA_TOOLSETS": "stock-data,crypto-data"
  }
}

  12. Set up the Alpaca MCP Server

    main

    To use the Alpaca MCP server, you must first obtain your Alpaca API keys and then configure the server within your MCP client (such as Claude Desktop or Claude Mobile).

    Prerequisites

    1. Get API Keys: You need valid Alpaca API keys. You can obtain these from your Alpaca account dashboard.
    2. Setup: Follow the specific configuration steps for your chosen client below.

    Claude Desktop Setup

    Configure your Claude Desktop configuration file to include the Alpaca MCP server. (Note: Specific configuration JSON structure is typically required in the claude_desktop_config.json file).

    Claude Mobile Setup

    Follow the mobile-specific integration steps provided in the official documentation to enable Alpaca capabilities on mobile devices.

    # Note: The specific configuration commands/JSON were not provided in this segment.
# Refer to the 'Setup' section in the full README for exact configuration blocks.