Stock Ticker MCP Server

Stock Ticker MCP Server ======================== Overview -------- The Stock Ticker MCP Server is a Model Context Protocol (MCP) server that provides real-time and historical stock market data using the Alpha Vantage API. This server enables Claude AI to access stock information through a standardized interface. Features -------- - Get current stock prices with detailed market information - Retrieve historical stock prices for specific dates - Support for all major stock symbols (NYSE, NASDAQ, etc.) - Comprehensive error handling and validation - Dockerized deployment for easy setup and portability - Built with FastMCP for optimal performance Prerequisites ------------- - Docker installed on your system - Alpha Vantage API key (free registration at https://www.alphavantage.co/support/#api-key) - Claude AI configured with MCP support - Ubuntu 24.04.3 or compatible Linux distribution Installation ------------ 1. Clone or download the project files 2. Navigate to the project directory 3. Build the Docker image 4. Configure environment variables 5. Run the container 6. Configure Claude AI to use the MCP server API Dependencies --------------- - Alpha Vantage API: Provides stock market data - Base URL: https://www.alphavantage.co/query - Documentation: https://www.alphavantage.co/documentation/ - Rate Limit: 25 requests per day (free tier) Available Tools -------------- 1. get_current_price(symbol) - Returns current stock price and market data - Parameters: symbol (string) - Stock ticker symbol (e.g., "AAPL") - Returns: price, change, volume, open/high/low, etc. 2. get_historical_price(symbol, date) - Returns historical stock data for a specific date - Parameters: - symbol (string) - Stock ticker symbol - date (string) - Date in YYYY-MM-DD format - Returns: open, high, low, close, volume for the specified date Configuration ------------ Environment Variables: - ALPHA_VANTAGE_API_KEY: Your Alpha Vantage API key (required) Port Configuration: - Default port: 8000 - Can be changed in Dockerfile or docker run command Security Features ---------------- - Non-root user execution in container - Minimal attack surface with slim Python image - Input validation and sanitization - Secure API key handling through environment variables - Health checks for container monitoring Troubleshooting -------------- Common Issues: 1. "API key not configured" - Set ALPHA_VANTAGE_API_KEY environment variable 2. "API call frequency limit reached" - You've exceeded the free tier limit 3. "Invalid symbol" - Check that the stock symbol is correct and exists 4. "No data available for date" - Date might be weekend/holiday or non-trading day 5. "Request timed out" - Network connectivity issues or API downtime Error Codes: - HTTP 401: Invalid API key - HTTP 429: Rate limit exceeded - HTTP 404: Symbol not found - Timeout: Network or API response issues Performance Notes ---------------- - Free Alpha Vantage tier allows 25 requests per day - Historical data requests are larger and may take longer - Container includes health checks for monitoring - Responses are cached by Alpha Vantage for some time Support and Documentation ------------------------ - Alpha Vantage API Documentation: https://www.alphavantage.co/documentation/ - FastMCP Documentation: https://github.com/pydantic/fastmcp - Model Context Protocol Specification: https://modelcontextprotocol.io/ Version Information ------------------ - Python: 3.11 - FastMCP: 0.2.0+ - HTTPX: 0.25.0+ - Container OS: Debian (slim) License and Usage ---------------- This software is provided as-is for educational and development purposes. Alpha Vantage API usage is subject to their terms of service. Please respect API rate limits and terms of use.