Alpha Vantage MCP Server

A comprehensive Model Context Protocol (MCP) server that provides access to Alpha Vantage's financial data APIs, including stocks, forex, crypto, commodities, and economic indicators.

🚀 Features

Core Stock APIs

• Real-time Quotes: Get current stock prices and metrics

• Time Series Data: Daily, weekly, monthly, and intraday data

• Symbol Search: Find stocks by company name or ticker

Fundamental Data

• Company Overview: Complete company information and financials

• Financial Statements: Income statement, balance sheet, cash flow

• Earnings Data: Historical earnings and earnings call transcripts

Technical Indicators

• Moving Averages: SMA, EMA, DEMA, TEMA, TRIMA, KAMA, MAMA, VWAP, T3

• Momentum Indicators: RSI, MACD, Stochastic, Williams %R, ROC, MOM

• Volatility Indicators: Bollinger Bands, ATR, NATR

• Volume Indicators: OBV, A/D Line, A/D Oscillator, MFI

Market Intelligence

• News Sentiment: AI-powered news analysis with sentiment scores

• Market Movers: Top gainers, losers, and most active stocks

• Market Status: Global exchange status and trading hours

Forex & Currencies

• Real-time Exchange Rates: Currency conversion rates

• FX Time Series: Historical forex data with multiple timeframes

Economic Indicators

• GDP Data: Real GDP and GDP per capita

• Federal Reserve: Interest rates, money supply

• Labor Statistics: Unemployment, nonfarm payrolls

• Inflation Data: CPI and inflation rates

Commodities

• Energy: WTI crude oil, Brent crude, natural gas

• Metals: Copper, aluminum

• Agriculture: Wheat, corn, cotton, sugar, coffee

Related MCP server: AlphaVantage-MCP

📦 Installation

Prerequisites

• Python 3.11 or higher

• uv package manager

• Alpha Vantage API key (free at alphavantage.co)

Setup

1. Clone and install:

   git clone https://github.com/yourusername/alpha-vantage-mcp-server
   cd alpha-vantage-mcp-server
   uv sync

2. Configure API key:

   cp .env.example .env
   # Edit .env and add your Alpha Vantage API key

3. Test the installation:

   uv run python test_server.py

🔧 Configuration

Environment Variables

Create a .env file with your Alpha Vantage API key:

# Required: Your Alpha Vantage API key
ALPHA_VANTAGE_KEY=your_api_key_here

# Optional: Debug mode
DEBUG=false

Rate Limits

• Free Tier: 25 requests per day, 5 requests per minute

• Premium Plans: Start at $49.99/month with higher limits

• Visit Alpha Vantage Premium for details

🎯 Usage with MCP Clients

Claude Desktop Configuration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "alpha-vantage": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/alpha-vantage-mcp-server",
        "alpha-vantage-mcp-server"
      ],
      "env": {
        "ALPHA_VANTAGE_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

The server provides 25+ comprehensive tools covering all major financial data categories:

Core Market Data

• get_current_stock_quote - Real-time stock quotes with clean formatting

• get_stock_time_series - Historical price data (daily, weekly, monthly, intraday)

• lookup_stock_symbol - Search stocks by company name or symbol

• get_global_markets_status - Worldwide exchange status and trading hours

Technical Analysis

• get_trend_indicators - SMA, EMA, WMA, MACD with preset configurations

• get_momentum_indicators - RSI, Stochastic, CCI, MFI indicators

• get_volatility_indicators - Bollinger Bands, ATR, SAR indicators

• get_volume_indicators - OBV, A/D Line, A/D Oscillator

Fundamental Data

• get_symbol_overview - Company profiles and key metrics

• get_financial_statements - Income statements, balance sheets, cash flow

• get_earning_data - Historical earnings with quarterly breakdowns

• get_corporate_actions - Dividend history and stock splits

Market Intelligence

• get_news_sentiment - AI-powered news analysis with sentiment scores

• get_top_gainers_losers - Market movers and most active stocks

• get_stock_insider_transactions - Insider trading activity

• analyze_stocks - Advanced analytics and statistical calculations

Forex & Crypto

• get_current_fx_rate - Real-time currency exchange rates

• get_fx_time_series - Historical forex data with multiple intervals

• get_current_crypto_quote - Current cryptocurrency market quotes

• get_crypto_time_series - Historical crypto price data

Economic Indicators

• get_growth_metrics - GDP and economic growth data

• get_rates_yields - Treasury yields and federal funds rates

• get_prices_inflation - CPI and inflation metrics

• get_labor_activity - Employment and labor market data

• get_commodities - Global commodities pricing data

Market Calendar

• get_market_calendar - Earnings announcements and IPO calendar

• get_listing_status - Stock listing and delisting information

• get_historical_options - Options trading data

🧪 Testing

Run the comprehensive test suite:

uv run python test_server.py

The test suite includes:

• ✅ Schema validation for all tools

• ✅ Input parameter validation

• ✅ Output format verification

• ✅ Error handling tests

• ✅ Rate limit awareness

📊 Example Usage

Get Stock Quote

# Through MCP client:
await get_current_stock_quote(symbol="AAPL")

Technical Analysis

# Get momentum indicators for Apple stock
await get_momentum_indicators(
    symbol="AAPL",
    interval="daily", 
    preset="standard"
)

Market Intelligence

# Get news sentiment for multiple stocks
await get_news_sentiment(
    tickers=["AAPL", "MSFT", "GOOGL"]
)

Economic Data

# Get latest GDP data
await get_growth_metrics(
    frequency="quarterly",
    seasonally_adjusted=true
)

Advanced Analytics

# Perform statistical analysis on stock data
await analyze_stocks(
    symbols=["AAPL", "MSFT"],
    interval="DAILY",
    calculations=["MEAN", "STDDEV", "CORRELATION"],
    series_range="6month"
)

🔍 API Coverage

This MCP server implements 25+ comprehensive tools that leverage Alpha Vantage's extensive API coverage:

• Core Market Data (4 unified tools covering 10+ endpoints)

• Technical Analysis (4 indicator packs covering 15+ indicators)

• Fundamental Data (4 tools covering company financials)

• Market Intelligence (4 tools for news, movers, and insider data)

• Forex & Crypto (4 tools for currency and crypto data)

• Economic Indicators (4 tools covering GDP, inflation, employment)

• Commodities & Calendar (3 tools for commodities and market events)

Each tool is designed for optimal usability with preset configurations and clean, structured outputs.

⚠️ Important Notes

Rate Limiting

• Free tier has strict limits (25 requests/day)

• Production usage requires premium subscription

• Server handles rate limiting gracefully

Data Format

• All responses follow Alpha Vantage's JSON structure

• CSV format supported for select endpoints

• Comprehensive error handling included

Best Practices

• Cache responses when possible

• Respect rate limits

• Use appropriate intervals for your use case

• Monitor API usage

🛠️ Development

Project Structure

alpha-vantage-mcp-server/
├── alpha_vantage_mcp_server/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py          # MCP server implementation
│   ├── handlers.py        # Unified tool function implementations
│   ├── api_helpers.py     # Alpha Vantage API client functions
│   └── tools.json         # Complete tool schema definitions
├── test_cases.json        # Test scenarios
├── test_server.py         # Test runner
├── pyproject.toml         # Project configuration
└── README.md

Adding New Tools

1. Add function implementation to handlers.py

2. Add tool schema definition to tools.json

3. Update TOOL_FUNCTIONS mapping in handlers.py

4. Add comprehensive test cases to test_cases.json

5. Run tests to ensure schema validation passes

📈 Roadmap

• Add more economic indicator tools

• Implement intelligent caching layer

• Add data export utilities

• Expand error handling and retry logic

• Add request batching optimization

• Create preset collections for common analysis workflows

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Ensure all tests pass

5. Submit a pull request

📄 License

[Add your license here]

🙏 Acknowledgments

• Alpha Vantage for providing the financial data API

• MCP for the protocol specification

• Claude and Anthropic for MCP client support

Ready to analyze financial markets with AI? Get your free Alpha Vantage API key and start exploring! 🚀📈