AlphaVantage MCP Server

A Model Context Protocol (MCP) server that provides comprehensive market data and fundamental analysis through the AlphaVantage API. Designed for integration with Claude Desktop and other MCP-compatible clients.

Requirements

• Python 3.10 - 3.12

• uv package manager

• AlphaVantage API key (get one free)

Installation

# Clone the repository
git clone <repo-url>
cd alphavantage_mcp

# Install dependencies
uv sync

Configuration

Set your AlphaVantage API key as an environment variable:

# macOS/Linux
export ALPHA_VANTAGE_API_KEY=your_key_here

# Windows (Command Prompt)
set ALPHA_VANTAGE_API_KEY=your_key_here

# Windows (PowerShell)
$env:ALPHA_VANTAGE_API_KEY="your_key_here"

Or create a .env file in the project directory:

ALPHA_VANTAGE_API_KEY=your_alphavantage_api_key

Server Configuration (Optional)

Running the Server

# Direct execution
uv run alphavantage-mcp-server

# Using launch script (macOS/Linux)
./launch-alphavantage.sh

# Using launch script (Windows)
launch-alphavantage.bat

Usage with Claude Desktop

Add to your Claude Desktop configuration file:

Option 1: Using launch script (recommended)

{
  "mcpServers": {
    "alphavantage-data": {
      "command": "/path/to/alphavantage_mcp/launch-alphavantage.sh",
      "env": {
        "ALPHA_VANTAGE_API_KEY": "your_key"
      }
    }
  }
}

Option 2: Using absolute path to uv

First, find your uv path: which uv

{
  "mcpServers": {
    "alphavantage-data": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": ["run", "alphavantage-mcp-server"],
      "cwd": "/path/to/alphavantage_mcp",
      "env": {
        "ALPHA_VANTAGE_API_KEY": "your_key"
      }
    }
  }
}

Note: GUI applications like Claude Desktop don't inherit your shell's PATH, so using absolute paths is more reliable than relying on uv being in PATH.

On Windows, use backslashes: "cwd": "C:\\path\\to\\alphavantage_mcp"

Available Tools

Fundamental Data

Market Data

News & Sentiment

Technical Analysis

Supported indicators (TechnicalIndicator enum):

• RSI - Relative Strength Index

• MACD - Moving Average Convergence Divergence

• BOLLINGER_BANDS - Bollinger Bands

• SMA - Simple Moving Average

• EMA - Exponential Moving Average

• STOCHASTIC - Stochastic Oscillator

• ADX - Average Directional Index

• WILLIAMS_R - Williams %R

Supported timeframes (TimeFrame enum):

• MINUTE - 1 minute

• FIVE_MINUTES - 5 minutes

• FIFTEEN_MINUTES - 15 minutes

• THIRTY_MINUTES - 30 minutes

• HOUR - 1 hour

• DAILY - Daily

• WEEKLY - Weekly

• MONTHLY - Monthly

Examples

Get company fundamentals:

"Get the company overview for AAPL"

Analyze price trends:

"Show me the daily prices for TSLA over the last 100 days"

Technical analysis:

"Calculate the RSI for MSFT with a 14-day period"

Market news:

"Get recent news about NVDA with sentiment analysis"

Development

# Install with dev dependencies
uv sync --extra dev

# Run the server directly
uv run alphavantage-mcp-server

# Run tests
uv run pytest

# Type checking
uv run mypy .

# Format code
uv run black .

API Rate Limits

The free AlphaVantage API tier allows 25 requests per day. Consider upgrading to a premium plan for higher limits.

Security Notes

• Never commit API keys to version control

• Use environment variables or secure secret management for API keys

• The server validates all inputs to prevent injection attacks