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)

| Variable | Description | Default | |----------|-------------|---------| | ALPHAVANTAGE_DEBUG | Enable debug mode | false | | ALPHAVANTAGE_PORT | Server port | 8002 | | ALPHAVANTAGE_LOG_LEVEL | Log level (DEBUG, INFO, WARNING, ERROR) | INFO |

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:

| Platform | Config Location | |----------|-----------------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

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

| Tool | Description | Parameters | |------|-------------|------------| | get_company_overview | Company fundamentals including PE ratio, market cap, EPS, margins, and more | symbol | | get_income_statement | Annual income statement data (last 20 periods) | symbol | | get_balance_sheet | Annual balance sheet data (last 20 periods) | symbol | | get_cash_flow | Annual cash flow statements (last 20 periods) | symbol | | get_earnings | Quarterly or annual earnings data | symbol, period (quarterly/annual) |

Market Data

| Tool | Description | Parameters | |------|-------------|------------| | get_daily_prices | Daily OHLCV data | symbol, outputsize (compact=100 days, full=20+ years) | | get_intraday_prices | Intraday price data | symbol, timeframe (TimeFrame enum), outputsize |

News & Sentiment

| Tool | Description | Parameters | |------|-------------|------------| | get_market_news | Market news with sentiment analysis | tickers (list), topics (list), time_from, time_to, limit |

Technical Analysis

| Tool | Description | Parameters | |------|-------------|------------| | get_technical_indicators | Calculate technical indicators | symbol, indicator (TechnicalIndicator enum), timeframe (TimeFrame enum), time_period |

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

MCP Servers