Kai Stock Market MCP

🚀 Stock Market MCP Server

This is a comprehensive Model Context Protocol (MCP) server for Indian and global stock market data, powered by yfinance. It features intelligent symbol resolution, real-time data, and advanced chart generation for both NSE/BSE and international markets.

✨ Features

Intelligent Symbol Resolution

• Smart Name-to-Symbol Conversion: You can use company names such as "Reliance", "Apple", and "TCS" instead of exact symbols.
• Fuzzy Matching: It can handle typos and partial names with confidence scoring.
• Context-Aware: It prioritizes Indian stocks (.NS/.BO) for regional users.
• Multi-Format Support: It accepts both exact symbols (RELIANCE.NS) and natural names (Reliance).

Real-Time Stock Data

• Live Quotes: It provides current prices, changes, volume, and market cap.
• Historical Data: It offers price history with configurable timeframes (from 1d to 10y+).
• Company Profiles: It includes detailed fundamentals, financial metrics, and business information.
• Multiple Stock Support: It supports batch processing for portfolio analysis.
• Fast Quotes: It enables quick price checks without full company details.

Advanced Chart Generation

• Professional Charts: It generates high-quality matplotlib visualizations with financial styling.
• Multiple Chart Types: It offers price charts, candlestick charts, volume analysis, and comparisons.
• Technical Indicators: It includes moving averages (MA20, MA50), VWAP, and volume trends.
• Comparative Analysis: It provides multi-stock performance visualization.
• Export Ready: It generates PNG format charts suitable for reports and presentations.

Comprehensive Financial Analysis

• Financial Statements: It includes income statements, balance sheets, and cash flow analysis.
• Earnings Intelligence: It provides historical earnings, upcoming dates, and analyst estimates.
• Analyst Coverage: It offers buy/sell/hold recommendations and price targets.
• Ownership Analysis: It includes institutional holdings, mutual funds, and major shareholders.
• Market Research: It provides revenue forecasts and earnings predictions.

Indian Market Optimization

• NSE/BSE Focus: It offers specialized support for Indian stock exchanges.
• Currency Formatting: It uses Rupee (₹) symbols and Indian number formats (Crores/Lakhs).
• NIFTY 50 Integration: It has a pre-loaded watchlist for market movers and screening.
• Major Indices: It provides real-time NIFTY 50, SENSEX, BANK NIFTY, and sectoral indices.
• Popular Stocks: It has over 100 pre-configured Indian companies for instant access.

📦 Installation

Prerequisites

• Python 3.11 or higher
• Environment variables configuration

Quick Start

1. Clone the repository and navigate to the project directory.
2. Create environment configuration:

cp .env.example .env

3. Configure your .env file:

AUTH_TOKEN=your_secure_auth_token_here
MY_NUMBER=your_validation_number_here

4. Install dependencies:

pip install -r requirements.txt

5. Start the server:

python stock_market_server.py

The server will be available at http://0.0.0.0:8087.

💻 Usage Examples

Smart Symbol Resolution

• Get real-time quote: get_stock_quote("Reliance") or get_stock_quote("RELIANCE.NS")
• Historical data: get_stock_history("TCS", "1y") or get_stock_history("Tata Consultancy", "1y")
• Company information: get_stock_info("Apple") or get_stock_info("AAPL")
• Multiple quotes: get_multiple_stock_quotes("Reliance,TCS,Infosys") or exact symbols

Market Analysis

• Index tracking: get_market_indices()
• Market movers: get_market_movers("gainers")
• Stock comparison: compare_stocks("RELIANCE.NS,TCS.NS") or compare_stocks("Reliance,TCS")
• Analyst research: get_analyst_recommendations("HDFC Bank")
• Price targets: get_analyst_price_targets("Apple")

Chart Generation

• Price chart: create_stock_chart("Reliance", "6mo") or create_stock_chart("RELIANCE.NS", "6mo")
• Comparison chart: create_comparison_chart("TCS,Infosys", "1y")
• Candlestick chart: create_candlestick_chart("Apple", "3mo")
• Volume analysis: create_volume_analysis_chart("HDFC Bank", "6mo")

Financial Analysis

• Earnings data: get_earnings_data("Microsoft")
• Financial statements: get_income_statement("TCS")
• Ownership analysis: get_major_holders("Reliance")
• Dividend history: get_stock_dividends("HDFC Bank")

Information Tools

• get_mcp_capabilities: Comprehensive guide to all features and capabilities
• get_mcp_help: Quick help and common usage examples
• get_supported_stocks: List of pre-loaded Indian and global companies
• stock_mcp_authors_info: Author name and resume link

📚 Documentation

Project Structure

stock-market-mcp/
├── stock_market_server.py    # Main server entry point
├── auth.py                   # Authentication provider
├── models.py                 # Data models and schemas
├── services/                 # Business logic layer
│   ├── stock_service.py      # Stock data operations
│   ├── market_data_service.py # Market data operations
│   └── chart_service.py      # Chart generation
└── tools/                    # MCP tool definitions
    ├── stock_tools.py        # Stock-related tools
    ├── market_analysis_tools.py # Market analysis tools
    └── chart_tools.py        # Chart generation tools

API Reference

Stock Data Tools

Supported Timeframes

• Intraday: 1d, 5d (hourly data)
• Short-term: 1mo, 3mo, 6mo (daily data)
• Medium-term: 1y, 2y (daily data)
• Long-term: 5y, 10y (weekly data)
• Special: ytd (year-to-date), max (all available data)

Symbol Formats & Examples

• Indian Stocks: Use company names or add .NS for NSE, .BO for BSE
  • Examples: "Reliance" → RELIANCE.NS, "TCS" → TCS.NS, "HDFC Bank" → HDFCBANK.NS
• Global Stocks: Use company names or standard ticker symbols
  • Examples: "Apple" → AAPL, "Microsoft" → MSFT, "Google" → GOOGL
• Market Indices: Yahoo Finance index symbols
  • Indian: ^NSEI (NIFTY 50), ^BSESN (SENSEX), ^NSEBANK (BANK NIFTY)
  • Global: ^GSPC (S&P 500), ^DJI (Dow Jones), ^IXIC (NASDAQ)

Smart Resolution Examples

• Indian Companies: "Reliance Industries", "Tata Consultancy", "HDFC Bank", "Bharti Airtel"
• Global Companies: "Apple Inc", "Microsoft Corporation", "Alphabet", "Amazon"
• Abbreviations: "TCS", "HUL", "L&T", "SBI", "ICICI"
• Partial Names: "Reliance", "Infosys", "HDFC"

🔧 Technical Details

Architecture

• Service-Oriented Design: It has a modular architecture with dedicated service layers.
• yfinance Integration: It gets real-time data from Yahoo Finance API with intelligent caching.
• FastMCP Framework: It is a high-performance MCP server implementation with async support.
• Pydantic Models: It uses type-safe data validation and serialization throughout.
• Bearer Authentication: It has a secure token-based authentication system.

Market Coverage

• Indian Markets: It fully supports NSE (.NS) and BSE (.BO) listed securities.
• Global Markets: It supports major international exchanges (NASDAQ, NYSE, LSE, etc.).
• Market Indices: It provides real-time tracking of over 20 Indian and global indices.
• Symbol Universe: It has over 1000 pre-loaded popular stocks with intelligent name resolution.

Data Services

• Real-time Quotes: It provides live pricing, volume, market cap, and change data.
• Historical Analysis: It offers comprehensive historical data with over 10 timeframe options.
• Technical Indicators: It includes moving averages, VWAP, volume analysis, and volatility metrics.
• Financial Metrics: It provides P/E ratios, P/B ratios, EPS, dividend yields, beta, and growth rates.
• News Integration: It includes the latest company news and market-moving events.

Visualization & Charts

• Professional Charts: It generates high-quality matplotlib charts optimized for financial data.
• Multiple Chart Types: It offers line charts, candlestick charts, volume analysis, and comparisons.
• Technical Analysis: It has built-in technical indicators and trend analysis.
• Export Formats: It generates PNG charts suitable for reports, presentations, and analysis.

Development Status

Current Implementation (v2.0+)

• Complete yfinance Integration: All over 25 stock data tools are fully implemented with error handling.
• Intelligent Symbol Resolution: It has advanced fuzzy matching with over 100 pre-loaded companies.
• Advanced Chart Generation: It generates professional matplotlib charts with technical indicators.
• Comprehensive Financial Data: It provides real-time quotes, historical data, earnings, and analyst coverage.
• Multi-Market Support: It seamlessly integrates Indian (NSE/BSE) and global markets.
• Production Ready: It has robust error handling, data validation, and performance optimization.

Recent Updates (2024)

• Full implementation of intelligent symbol resolution system.
• Added over 15 new financial analysis tools (earnings, recommendations, price targets).
• Enhanced chart generation with volume analysis and VWAP indicators.
• Comprehensive Indian market coverage with NIFTY 50 focus.
• Professional chart styling and advanced data visualization.
• Robust error handling and graceful fallback mechanisms.
• Smart caching and performance optimizations.

Tool Coverage

• Stock Data: 12 tools covering quotes, history, news, dividends, splits.
• Financial Analysis: 8 tools for earnings, statements, and analyst coverage.
• Market Analysis: 8 tools for indices, movers, comparisons, and research.
• Chart Generation: 4 tools for various chart types and technical analysis.
• Utilities: 5 tools for search, resolution, help, capabilities, and author information.

Contributing

This project uses modern Python development practices:

Development Setup

# Clone and install development dependencies
git clone <repository-url>
cd stock-market-mcp
pip install -e ".[dev]"

Code Quality & Standards

• Formatting: Black code formatter with 120-character line limit.
• Import Organization: isort for consistent import ordering.
• Type Safety: mypy type checking with strict mode.
• Testing: pytest framework for comprehensive test coverage.
• Documentation: Comprehensive docstrings and API documentation.

Code Architecture

• Async/Await: Non-blocking operations throughout for high performance.
• Service Layer: Dedicated services for stock data, market data, and chart generation.
• Model Validation: Pydantic models for type-safe data validation.
• Error Handling: Comprehensive error handling with graceful degradation.
• Caching: Intelligent caching to reduce API calls and improve response times.

Docker & Deployment

Quick Start with Docker

# Build and run locally
docker build -t stock-market-mcp .
docker run -p 8087:8087 \
  -e AUTH_TOKEN=your-token \
  -e MY_NUMBER=91xxxxxxxxxx \
  stock-market-mcp

Railway Deployment

This application is optimized for Railway hosting with:

• Dockerfile-based deployment
• Dynamic port binding
• Health check endpoints
• Minimal Docker image

See RAILWAY_DEPLOY.md for detailed deployment instructions.

Local Development with Docker Compose

# Copy environment variables
cp .env.example .env
# Edit .env with your values

# Start the service
docker-compose up --build