AlphaVantage 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