# 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](https://docs.astral.sh/uv/) package manager
- AlphaVantage API key ([get one free](https://www.alphavantage.co/support/#api-key))
## Installation
```bash
# Clone the repository
git clone <repo-url>
cd alphavantage_mcp
# Install dependencies
uv sync
```
## Configuration
Set your AlphaVantage API key as an environment variable:
```bash
# 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
```bash
# 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)**
```json
{
"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`
```json
{
"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
```bash
# 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
