NwayOoKhine/Stock-MCP-Server

Stock Market Analysis MCP Server

A comprehensive Model Context Protocol (MCP) server that provides real-time stock market data and analysis capabilities. Built with FastMCP, this server offers both MCP protocol support for AI assistants and a REST API with an interactive Streamlit frontend.

🚀 Features

Available Analysis Tools:

• Stock Price - Get current stock price and daily change
• Historical Data - Fetch historical price data with interactive charts
• Moving Averages - Calculate 20, 50, and 200-day moving averages
• RSI Indicator - Compute 14-day Relative Strength Index
• Stock Comparison - Side-by-side comparison of multiple stocks
• Stock Screening - Screen stocks by sector and other criteria
• Company Information - Get fundamental data and business summary

Multiple Access Methods:

• 🎨 Streamlit Frontend - Interactive web interface (Recommended)
• 🌐 REST API - HTTP endpoints for web applications
• 🔧 MCP Protocol - For AI assistant integration

🛠️ Tech Stack

Core Technologies:

• Python 3.11+ - Main programming language
• FastMCP - Model Context Protocol implementation
• FastAPI - Modern, fast web framework for REST API
• Streamlit - Interactive web application framework
• Uvicorn - Lightning-fast ASGI server

Data & Analysis:

• yfinance - Yahoo Finance API for real-time stock data
• finvizfinance - FinViz API for stock screening
• pandas - Data manipulation and analysis
• plotly - Interactive charting and visualization

Additional Libraries:

• Pydantic - Data validation and serialization
• httpx - Async HTTP client for API calls

📊 Quick Start - Streamlit Demo

Installation:

git clone https://github.com/NwayOoKhine/Stock-MCP-Server.git
cd Stock-MCP-Server
pip install -r requirements.txt

Run the Application:

Option 1: Streamlit Frontend (Recommended)

streamlit run frontend/streamlit_app.py

Opens interactive demo at: http://localhost:8501

Option 2: MCP + REST API Server

python -m src.stock_mcp_server

• MCP Server: http://127.0.0.1:8000/sse/
• REST API: http://127.0.0.1:8000/api/
• API Docs: http://127.0.0.1:8000/docs

🎯 Using the Streamlit Interface

The Streamlit app provides an intuitive interface for all stock analysis features:

1. Stock Price Lookup - Enter any stock symbol (e.g., AAPL, MSFT, GOOGL)
2. Historical Charts - View price trends over different periods
3. Technical Analysis - Calculate moving averages and RSI
4. Stock Comparison - Compare multiple stocks side-by-side
5. Market Screening - Find stocks by sector
6. Company Research - Get detailed fundamental data
7. Interactive Charts - Candlestick charts with technical indicators

Example Usage:

• Enter "AAPL" to get Apple's current price
• Compare "AAPL,MSFT,GOOGL,NVDA" for tech stock analysis
• Screen technology sector stocks
• Generate interactive charts with moving averages

🏗️ Architecture

src/
├── models.py          # Pydantic request/response models
├── mcp_tools.py       # FastMCP tool definitions  
├── api_routes.py      # FastAPI route handlers
├── stock_mcp_server.py # Main server integration
└── stock_analyzer.py   # Core stock analysis logic

frontend/
└── streamlit_app.py   # Interactive web interface

🔧 REST API Usage

When running the server, visit http://127.0.0.1:8000/docs for interactive API documentation.

Example API Calls:

# Get stock price
curl -X POST "http://127.0.0.1:8000/api/stock-price" \
     -H "Content-Type: application/json" \
     -d '{"symbol": "AAPL"}'

# Calculate RSI
curl -X POST "http://127.0.0.1:8000/api/rsi" \
     -H "Content-Type: application/json" \
     -d '{"symbol": "AAPL"}'

# Get moving averages
curl -X POST "http://127.0.0.1:8000/api/moving-averages" \
     -H "Content-Type: application/json" \
     -d '{"symbol": "AAPL"}'

🤖 MCP Integration

This server implements the Model Context Protocol, making it compatible with MCP-enabled AI assistants. The same analysis tools available in the Streamlit interface can be accessed by AI assistants through the MCP protocol.

Available MCP Tools:

• get_stock_price - Current price and daily change
• get_stock_history - Historical price data
• calculate_moving_averages - Technical indicators
• calculate_rsi - Momentum indicator
• compare_stocks - Multi-stock comparison
• screen_stocks - Stock screening
• get_company_info - Fundamental analysis

📊 Data Sources

• Yahoo Finance (yfinance) - Real-time and historical stock data
• FinViz (finvizfinance) - Stock screening and fundamental data

🎯 Use Cases

• Investment Research - Get real-time data and technical analysis
• Portfolio Monitoring - Track multiple stocks simultaneously
• Market Screening - Find stocks matching specific criteria
• Educational - Learn about technical indicators and analysis
• API Integration - Add financial capabilities to applications

🛠️ Development

Project Structure:

• Modular design with separated concerns
• Comprehensive error handling for robust operation
• Dual protocol support (MCP + REST) for flexibility
• Interactive frontend for user-friendly access

Extending the Server:

The modular architecture makes it easy to add new analysis tools:

1. Add function to stock_analyzer.py
2. Add MCP tool to mcp_tools.py
3. Add REST endpoint to api_routes.py
4. Update Streamlit UI in frontend/streamlit_app.py

🤝 Contributing

This project demonstrates MCP server implementation best practices. Feel free to extend with additional financial tools or integrate with other platforms.

📄 License

Open source - feel free to use and modify for your projects!