alpaca-mcp

Alpaca MCP Server

A Model Context Protocol (MCP) server that provides real-time access to cryptocurrency market data through the Alpaca API. This server implements a standardized interface for retrieving cryptocurrency data.

Features

• Daily, weekly, and monthly cryptocurrency time series data
• Latest crypto exchange rates
• Historical bar/candle data
• Built-in error handling and rate limit management

Installation

Using Claude Desktop

Installing via Docker

• Clone the repository and build a local image to be utilized by your Claude desktop client

cd alpaca-mcp
docker build -t mcp/alpaca .

• Change your claude_desktop_config.json to match the following, replacing REPLACE_API_KEY and REPLACE_API_SECRET with your actual keys:

claude_desktop_config.json path

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

{
  "mcpServers": {
    "alpaca": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-e",
        "ALPACA_API_KEY",
        "-e",
        "ALPACA_API_SECRET",
        "mcp/alpaca"
      ],
      "env": {
        "ALPACA_API_KEY": "REPLACE_API_KEY",
        "ALPACA_API_SECRET": "REPLACE_API_SECRET"
      }
    }
  }
}

Installing via UV (Fast Python Package Installer)

UV is a modern Python package installer that can simplify the installation process. To use UV with alpaca-mcp:

1. First, install UV if you don't have it already:

# Using pip
pip install uv

# Using brew on macOS
brew install uv

2. Configure your Claude Desktop config file to use UV:

{
  "mcpServers": {
    "alpaca": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/alpaca-mcp",
        "run",
        "alpaca-mcp"
      ],
      "env": {
        "ALPACA_API_KEY": "REPLACE_API_KEY",
        "ALPACA_API_SECRET": "REPLACE_API_SECRET"
      }
    }
  }
}

3. Install the package with UV:

# Clone the repository
git clone https://github.com/berlinbra/alpaca-mcp.git
cd alpaca-mcp

# Install dependencies using UV
uv pip install -e .

4. Run the server using UV:

uv run alpaca_mcp/server.py

5. For debugging purposes, you can use the MCP inspector:

npx @modelcontextprotocol/inspector uv --directory /path/to/alpaca-mcp run src/alpaca_mcp/server.py

Standard Development Setup

# Clone the repository
git clone https://github.com/berlinbra/alpaca-mcp.git
cd alpaca-mcp

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package in development mode
pip install -e .

Available Tools

Currently, the server implements the following tool:

• get-crypto-bars: Get historical bar/candle data for cryptocurrencies

More tools will be added in the future.

get-crypto-bars

Input Schema:

{
    "symbol": {
        "type": "string",
        "description": "Cryptocurrency symbol (e.g., BTC/USD, ETH/USD)"
    },
    "timeframe": {
        "type": "string",
        "description": "Timeframe for bars (e.g., 1Day, 1Hour, 1Min)",
        "default": "1Day"
    },
    "start": {
        "type": "string",
        "description": "Start date in YYYY-MM-DD format"
    },
    "limit": {
        "type": "integer",
        "description": "Maximum number of bars to return",
        "default": 10
    }
}

Example Response:

Cryptocurrency bars for BTC/USD (1Day):

Date: 2025-04-10
Open: $68750.12
High: $69200.45
Low: $67900.78
Close: $68900.32
Volume: 12345.67
---
Date: 2025-04-11
Open: $68900.32
High: $70100.55
Low: $68400.21
Close: $69800.44
Volume: 15678.90

Error Handling

The server includes comprehensive error handling for various scenarios:

• Rate limit exceeded
• Invalid API key
• Network connectivity issues
• Timeout handling
• Malformed responses

Error messages are returned in a clear, human-readable format.

Prerequisites

• Python 3.12 or higher
• httpx
• mcp
• alpaca-py
• python-dotenv (for loading environment variables)

License

This MCP server is licensed under the MIT License.