📈 Alpha Vantage MCP Server

Professional-grade Model Context Protocol (MCP) integration for the Alpha Vantage financial API. Seamlessly access real-time market data, company fundamentals, and advanced analytics within Claude Desktop and other MCP-compatible environments.

⚡ Quick Start

Claude Desktop Installation

# Install and configure with one command
npx alpha-vantage-mcp-server init --api-key YOUR_API_KEY

# Or install globally
npm install -g alpha-vantage-mcp-server

Claude Code Installation

# Method 1: NPX Version (Recommended for global compatibility)
claude mcp add-json alpha-vantage-mcp '{"command": "npx", "args": ["-y", "alpha-vantage-mcp-server@latest", "start"], "env": {"ALPHA_VANTAGE_API_KEY": "your_api_key_here", "LOG_LEVEL": "info"}}'

# Method 2: Local Development (after git clone + npm install + npm run build)
claude mcp add alpha-vantage-mcp node path/to/Alpha-Vantage-MCP/dist/index.js

# Verify installation
claude mcp list
claude mcp get alpha-vantage-mcp

Get Your API Key

1. Visit Alpha Vantage
2. Sign up for a free API key
3. Use the key in the installation command above

Verify Installation

# For Claude Desktop
alpha-vantage-mcp health  # Check server status
alpha-vantage-mcp tools   # List available tools

# For Claude Code
claude mcp list           # Check MCP server status
claude mcp get alpha-vantage-mcp  # Get detailed server info

🎯 Core Features

📊 Market Data & Analytics

• Real-time Quotes: Live OHLCV data with volume
• Historical Data: Intraday, daily, weekly, monthly time series
• Technical Indicators: 20+ professional trading indicators (RSI, MACD, SMA, EMA)
• Market Intelligence: Company fundamentals, earnings, financial statements

🧠 AI-Powered Intelligence

• News Sentiment: AI-powered sentiment analysis on market news
• Company Research: Comprehensive fundamental analysis
• Sector Analytics: Cross-sector performance comparisons
• Risk Assessment: Volatility and risk metrics

🚀 Enterprise-Grade Infrastructure

• Smart Rate Limiting: Token bucket algorithm with auto-tier detection
• Intelligent Caching: Optimized TTL for different data frequencies
• Error Resilience: Circuit breaker, exponential backoff, graceful degradation
• Performance Monitoring: Built-in health checks and metrics

🛠️ 25+ Professional Tools

Price Data Tools

| Tool | Description | Use Case | |------|-------------|----------| | av_global_quote | Real-time stock quotes | Current market pricing | | av_time_series_daily | Daily OHLCV data | Trend analysis, backtesting | | av_time_series_intraday | High-frequency data | Day trading, scalping | | av_symbol_search | Symbol lookup | Company discovery | | av_market_status | Market hours | Trading session planning | | av_exchange_rate | Currency conversion | International investing |

Intelligence & Fundamentals

| Tool | Description | Use Case | |------|-------------|----------| | av_company_overview | Complete company profile | Investment research | | av_income_statement | P&L statements | Profitability analysis | | av_balance_sheet | Financial position | Solvency assessment | | av_earnings | Earnings data | Growth analysis | | av_news_sentiment | AI news analysis | Market psychology |

Technical Analysis

| Tool | Description | Parameters | |------|-------------|------------| | av_rsi | Relative Strength Index | symbol, interval, time_period | | av_sma | Simple Moving Average | symbol, interval, time_period | | av_ema | Exponential Moving Average | symbol, interval, time_period | | av_macd | MACD Oscillator | symbol, interval, periods | | av_stoch | Stochastic Oscillator | symbol, interval, parameters |

💡 Usage Examples

Claude Desktop Integration

Once configured, use natural language queries:

"Get Apple's current stock price and today's performance"
→ Uses av_global_quote for real-time AAPL data

"Show me Microsoft's revenue growth over the last 3 years"  
→ Uses av_income_statement for fundamental analysis

"What's the sentiment on Tesla stock in recent news?"
→ Uses av_news_sentiment for market psychology analysis

"Calculate the 50-day moving average for SPY"
→ Uses av_sma for technical analysis

Direct API Usage

import { AlphaVantageMCPServer } from 'alpha-vantage-mcp-server';

const server = new AlphaVantageMCPServer();
await server.start();

// Server automatically handles:
// - Rate limiting (5 req/min free, 75 req/min premium)
// - Intelligent caching with appropriate TTL
// - Error handling with exponential backoff
// - Request queuing and optimization

🏗️ Architecture

Component Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude IDE    │───▶│   MCP Server     │───▶│ Alpha Vantage   │
│                 │    │                  │    │      API        │
│ • Natural Lang  │    │ • 25+ Tools      │    │ • Market Data   │
│ • Conversations │    │ • Rate Limiting  │    │ • Intelligence  │
│ • Auto-complete │    │ • Smart Caching  │    │ • Real-time     │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Key Components

• MCP Protocol Handler: Standards-compliant tool interface
• Alpha Vantage Client: Optimized API communication layer
• Rate Limiter: Token bucket with intelligent queuing
• Cache Manager: Multi-tier caching with smart TTL
• Error Handler: Circuit breaker with exponential backoff

⚙️ Configuration

Environment Variables

# Required
ALPHA_VANTAGE_API_KEY=your_api_key_here

# Optional  
ALPHA_VANTAGE_PREMIUM=true          # Enable premium rate limits
LOG_LEVEL=info                      # Logging level
NODE_ENV=production                 # Environment mode

Configuration Files

Claude Desktop Config

The init command automatically configures ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "alpha-vantage": {
      "command": "npx",
      "args": ["-y", "alpha-vantage-mcp-server@latest", "start"],
      "env": {
        "ALPHA_VANTAGE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code Config

Stored in ~/.claude.json for your project:

{
  "mcpServers": {
    "alpha-vantage-mcp": {
      "command": "npx",
      "args": ["-y", "alpha-vantage-mcp-server@latest", "start"],
      "env": {
        "ALPHA_VANTAGE_API_KEY": "your_api_key_here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

📊 Performance & Reliability

Rate Limiting

• Free Tier: 5 requests/minute with intelligent queuing
• Premium Tier: 75 requests/minute (auto-detected)
• Burst Handling: Token bucket algorithm prevents API violations

Caching Strategy

• Real-time data: 1 minute TTL
• Daily data: 1 hour TTL
• Fundamental data: 24 hours TTL
• News data: 30 minutes TTL

Error Handling

• Circuit Breaker: Automatic failure detection and recovery
• Exponential Backoff: Intelligent retry with increasing delays
• Graceful Degradation: Fallback to cached data when possible

🧪 Testing & Validation

Health Check

alpha-vantage-mcp health

Tool Verification

alpha-vantage-mcp tools

Live Data Test

# Test with popular symbols
echo "Testing with AAPL..." && \
node -e "
  const server = require('@alpha-vantage/mcp-server');
  // Test implementation
"

📚 API Reference

Price Data Methods

av_global_quote(symbol: string): GlobalQuote
av_time_series_daily(symbol: string, outputsize?: 'compact' | 'full'): TimeSeriesData
av_time_series_intraday(symbol: string, interval: '1min'|'5min'|'15min'|'30min'|'60min'): TimeSeriesData
av_symbol_search(keywords: string): SymbolSearchResult[]

Intelligence Methods

av_company_overview(symbol: string): CompanyProfile
av_income_statement(symbol: string): FinancialStatement
av_news_sentiment(tickers?: string, topics?: string, limit?: number): NewsAnalysis

Technical Analysis Methods

av_rsi(symbol: string, interval: string, time_period?: number): TechnicalIndicator
av_sma(symbol: string, interval: string, time_period?: number): MovingAverage
av_macd(symbol: string, interval: string): MACDIndicator

🔧 CLI Commands

# Initialize Claude Desktop integration  
alpha-vantage-mcp init [--api-key KEY]

# Start MCP server manually
alpha-vantage-mcp start [--log-level LEVEL]

# Health and diagnostics
alpha-vantage-mcp health
alpha-vantage-mcp tools

# Help and version
alpha-vantage-mcp --help
alpha-vantage-mcp --version

🛡️ Security & Privacy

• API Key Security: Environment variable storage only
• No Data Persistence: All data handled in memory
• Request Validation: Comprehensive input sanitization
• Error Privacy: Sensitive information filtered from logs
• Rate Limit Protection: Prevents API key blocking

🚀 Advanced Usage

Custom Configurations

// Advanced server configuration
const config = {
  rateLimit: { requestsPerMinute: 75 },
  cache: { enabled: true, ttl: { realtime: 30 } },
  retry: { attempts: 5, backoffMs: 2000 }
};

Batch Operations

// Multiple symbol analysis
const symbols = ['AAPL', 'MSFT', 'GOOGL'];
// Server automatically queues and rate-limits requests

Real-time Monitoring

// Continuous market monitoring
// Built-in health checks and performance metrics

🔧 Troubleshooting

Claude Code Issues

MCP Server Not Connecting:

# Check server status
claude mcp list
claude mcp get alpha-vantage-mcp

# Remove and re-add if needed
claude mcp remove alpha-vantage-mcp -s local
claude mcp add-json alpha-vantage-mcp '{"command": "npx", "args": ["-y", "alpha-vantage-mcp-server@latest", "start"], "env": {"ALPHA_VANTAGE_API_KEY": "your_key"}}'

API Key Issues:

# Verify API key is set
echo $ALPHA_VANTAGE_API_KEY

# Test API key directly
ALPHA_VANTAGE_API_KEY=your_key npx alpha-vantage-mcp-server health

NPX Cache Issues:

# Clear NPX cache if corrupted
rm -rf ~/.npm/_npx
npm cache clean --force

# Test fresh installation
npx alpha-vantage-mcp-server@latest tools

Claude Desktop Issues

Server Disconnecting:

• Check logs: /Users/$(whoami)/Library/Logs/Claude/mcp-server-alpha-vantage-mcp.log
• Restart Claude Desktop after configuration changes
• Ensure API key is properly set in environment

MCP Inspector Testing:

# Test your server with official MCP debugging tool
npx @modelcontextprotocol/inspector npx alpha-vantage-mcp-server@latest start
# Opens browser at http://localhost:6274

📞 Support & Resources

• Documentation: Complete API reference and examples in this README
• Issues: Report bugs via NPM package page
• Alpha Vantage Docs: Official API Documentation
• MCP Specification: Model Context Protocol
• MCP Inspector: Debugging Tool

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

This is a community-driven project. For contributions:

1. Report issues via the NPM package page
2. Suggest improvements via package discussions
3. Share usage examples and feedback

Built for professional financial analysis and investment research 📊
Compatible with Claude Desktop, Claude Code, and all MCP-enabled environments 🤖

Get started in under 2 minutes with npx alpha-vantage-mcp-server init