Skip to main content
Glama

Enhanced MCP Stock Query System

by fjing1

Enhanced MCP Stock Query System

An intelligent, production-ready stock data retrieval system built on the Model Context Protocol (MCP) that combines AI-powered query understanding with reliable financial data access. The system uses Google's Gemini AI to interpret natural language queries and automatically selects the appropriate tools to fetch comprehensive stock market information.

๐Ÿš€ Features

Core Functionality

  • ๐Ÿค– AI-Powered Query Understanding: Uses Google Gemini to interpret natural language stock queries

  • ๐Ÿ“Š Dual Data Sources: Primary Yahoo Finance API with CSV fallback for reliability

  • ๐Ÿ”„ Automatic Tool Selection: Intelligent mapping of user queries to appropriate stock tools

  • ๐Ÿ’ฌ Interactive Chat Interface: Enhanced command-line interface with error handling

  • ๐Ÿ›ก๏ธ Robust Error Handling: Comprehensive fallback mechanisms and error recovery

  • โšก Asynchronous Processing: High-performance async operations for better responsiveness

Enhanced MCP Features

  • ๐Ÿ“‹ MCP Resources: Exposes stock data and market information as discoverable resources

  • ๐ŸŽฏ MCP Prompts: Pre-built prompt templates for stock analysis and comparisons

  • ๐Ÿ”ง Enhanced Tools: Improved tools with better validation and error handling

  • ๐Ÿ“ˆ Market Summary: New tool for getting overview of key market data

Production-Ready Improvements

  • ๐Ÿ—๏ธ Type Safety: Comprehensive type hints throughout the codebase

  • ๐Ÿ“ Comprehensive Logging: Structured logging for debugging and monitoring

  • โš™๏ธ Configuration Management: Environment-based configuration with validation

  • ๐Ÿงช Testing Suite: Unit tests for core functionality

  • ๐Ÿ”’ Input Validation: Sanitization and validation of all user inputs

  • ๐Ÿ”„ Retry Logic: Automatic retry with exponential backoff for failed operations

๐Ÿ“‹ Available Tools

get_stock_price

  • Purpose: Retrieve current stock price for a single symbol

  • Parameters: symbol (string): Stock ticker symbol (e.g., "AAPL", "MSFT")

  • Enhanced Features: Input validation, detailed error messages, data source indication

compare_stocks

  • Purpose: Compare prices between two stock symbols with percentage differences

  • Parameters:

    • symbol1 (string): First stock ticker symbol

    • symbol2 (string): Second stock ticker symbol

  • Enhanced Features: Percentage calculations, data source tracking, comprehensive comparisons

get_market_summary

  • Purpose: Get overview of key market stocks and data availability

  • Parameters: None

  • Features: Shows availability status, data sources, and key stock prices

๐Ÿ”ง MCP Resources

stock_data

  • URI: stock://data

  • Description: Information about available stocks and data sources

  • Content: JSON with available symbols, data sources, and freshness information

market_info

  • URI: stock://market-info

  • Description: Server capabilities and market information

  • Content: JSON with server features and supported operations

๐ŸŽฏ MCP Prompts

stock_analysis

  • Purpose: Template for comprehensive stock analysis

  • Usage: Provides structured approach to analyzing individual stocks

comparison_prompt

  • Purpose: Template for comparing multiple stocks

  • Usage: Guides comparative analysis between different stocks

๐Ÿ—๏ธ Architecture

The system consists of two main components with enhanced error handling and configuration:

Enhanced MCP Server (mcp_server.py)

  • Provides stock data tools through the MCP protocol

  • Implements Yahoo Finance API integration with robust CSV fallback

  • Exposes MCP resources and prompts for better discoverability

  • Comprehensive error handling with custom exception types

  • Input validation and sanitization

  • Structured logging for monitoring

Enhanced MCP Client (mcp_client.py)

  • Handles user input and natural language processing

  • Connects to the MCP server via stdio communication

  • Uses Gemini AI to identify appropriate tools and arguments

  • Configuration management and environment validation

  • Retry logic with exponential backoff

  • Interactive user session with graceful error handling

๐Ÿ“ฆ Installation

Prerequisites

  • Python 3.10 or higher

  • Google AI API key (Gemini)

  • Internet connection for Yahoo Finance data

Setup Steps

  1. Clone or download the project files

  2. Install dependencies:

    pip install -r requirements.txt
  3. Configure environment variables:

    cp .env.example .env # Edit .env with your actual values
  4. Required environment variables (.env):

    GEMINI_API_KEY=your_gemini_api_key_here
  5. Optional environment variables:

    MCP_SERVER_CWD=/path/to/your/project MCP_MAX_RETRIES=3 MCP_TIMEOUT_SECONDS=30 LOG_LEVEL=INFO
  6. Verify data file: Ensure stocks_data.csv is present with the correct format:

    symbol,price,last_updated AAPL,175.64,2024-01-15 MSFT,330.21,2024-01-15 GOOGL,135.45,2024-01-15

๐Ÿš€ Usage

Starting the System

  1. Run the enhanced client:

    python mcp_client.py
  2. Enter natural language queries:

    What is your query? โ†’ What's the current price of Apple? What is your query? โ†’ Compare stock prices of Apple and Microsoft What is your query? โ†’ Get market summary
  3. Exit commands:

    • Type quit, exit, or q to stop

    • Use Ctrl+C for immediate exit

Example Interactions

Single Stock Query:

Input: "What's the price of AAPL?" Output: The current price of AAPL is $175.64 (from Yahoo Finance)

Stock Comparison with Percentage:

Input: "Compare Apple and Microsoft stocks" Output: AAPL ($175.64 YF) is lower than MSFT ($330.21 YF) by $154.57 (87.9%).

Market Summary:

Input: "Get market summary" Output: Market Summary (5/5 stocks available): AAPL: $175.64 (Live) MSFT: $330.21 (Live) GOOGL: $135.45 (Cached (2024-01-15)) AMZN: $145.32 (Live) TSLA: $250.87 (Live) Data sources: Yahoo Finance (primary), Local CSV (fallback)

Fallback Data Example:

Input: "Get Tesla stock price" Output: The current price of TSLA is $250.87 (from local data, last updated: 2024-01-15)

๐Ÿ“ Project Structure

enhanced-mcp-stock-system/ โ”œโ”€โ”€ mcp_client.py # Enhanced client with AI integration โ”œโ”€โ”€ mcp_server.py # Enhanced server with MCP resources/prompts โ”œโ”€โ”€ stocks_data.csv # Fallback stock data (corrected format) โ”œโ”€โ”€ requirements.txt # Updated dependencies with dev tools โ”œโ”€โ”€ .env.example # Environment configuration template โ”œโ”€โ”€ .env # Your actual environment variables (create this) โ”œโ”€โ”€ tests/ โ”‚ โ”œโ”€โ”€ test_mcp_server.py # Unit tests for server functionality โ”‚ โ””โ”€โ”€ __init__.py # Test package initialization โ”œโ”€โ”€ README.md # This comprehensive documentation โ””โ”€โ”€ .gitignore # Git ignore file (recommended)

๐Ÿงช Testing

Running Tests

# Install test dependencies pip install pytest pytest-asyncio # Run all tests pytest tests/ # Run with coverage pytest tests/ --cov=. --cov-report=html # Run specific test file pytest tests/test_mcp_server.py -v

Test Coverage

  • Stock symbol validation

  • CSV data handling and error cases

  • Yahoo Finance integration mocking

  • Fallback mechanism testing

  • Error handling scenarios

โš™๏ธ Configuration

Environment Variables

Variable

Required

Default

Description

GEMINI_API_KEY

Yes

-

Google Gemini API key for AI processing

MCP_SERVER_CWD

No

Current directory

Working directory for MCP server

MCP_MAX_RETRIES

No

3

Maximum retry attempts for failed operations

MCP_TIMEOUT_SECONDS

No

30

Timeout for MCP operations

LOG_LEVEL

No

INFO

Logging level (DEBUG, INFO, WARNING, ERROR)

CSV_FILE_PATH

No

stocks_data.csv

Path to fallback CSV data file

CSV Data Format

The fallback CSV file must follow this exact structure:

symbol,price,last_updated AAPL,175.64,2024-01-15 MSFT,330.21,2024-01-15 GOOGL,135.45,2024-01-15 AMZN,145.32,2024-01-15 META,310.21,2024-01-15 TSLA,250.87,2024-01-15

Required columns:

  • symbol: Stock ticker symbol (uppercase recommended)

  • price: Current stock price (numeric)

  • last_updated: Date when price was last updated (YYYY-MM-DD format)

๐Ÿ” Data Sources

Primary: Yahoo Finance

  • Real-time stock data via yfinance library

  • Comprehensive market coverage

  • Automatic retry mechanisms

  • Live market data during trading hours

Fallback: Local CSV

  • Offline data access when Yahoo Finance is unavailable

  • Customizable stock universe

  • Fast local lookups

  • Timestamped data for freshness tracking

๐Ÿ› Troubleshooting

Common Issues

Network/SSL Issues with Yahoo Finance

Error: TLS connect error or OpenSSL invalid library

Causes:

  • Corporate networks with strict SSL/TLS policies

  • Outdated OpenSSL libraries or certificates

  • VPN or proxy configurations blocking financial APIs

  • Restricted network environments

Solutions:

  1. System automatically falls back to local CSV data

  2. Verify your query symbol exists in stocks_data.csv

  3. Update system OpenSSL libraries

  4. Configure proxy settings if behind corporate firewall

  5. Contact network administrator for API access permissions

Configuration Errors

Error: Configuration error: GEMINI_API_KEY environment variable is required

Solution:

  1. Copy .env.example to .env

  2. Add your actual Gemini API key

  3. Ensure .env file is in the project root directory

MCP Connection Issues

Error: MCP connection error: Server script not found

Solutions:

  1. Verify mcp_server.py is in the correct directory

  2. Check the MCP_SERVER_CWD environment variable

  3. Ensure Python is in your system PATH

  4. Verify file permissions

Data Retrieval Issues

Error: Could not retrieve price for SYMBOL

Solutions:

  1. Verify stock symbol is correct (use uppercase)

  2. Check internet connection for Yahoo Finance

  3. Ensure stocks_data.csv exists and has correct format

  4. Check CSV file has all required columns

Debug Mode

Enable detailed debugging by setting:

LOG_LEVEL=DEBUG

This provides detailed information about:

  • MCP connection status

  • AI tool identification process

  • Data source selection logic

  • Detailed error traces

๐Ÿ“Š Performance Considerations

Optimization Features

  • Asynchronous operations for better responsiveness

  • Intelligent caching of frequently requested data

  • Efficient CSV parsing with pandas

  • Connection reuse for external APIs

  • Graceful degradation when services are unavailable

Scalability Notes

  • Current implementation is designed for moderate query volumes

  • For high-volume production use, consider:

    • Adding Redis for caching

    • Implementing connection pooling

    • Using a proper database instead of CSV

    • Adding rate limiting for external APIs

๐Ÿ”’ Security Considerations

Implemented Security Features

  • Input validation and sanitization

  • Environment-based configuration (no hardcoded secrets)

  • Proper error handling without information leakage

  • Type checking to prevent injection attacks

Recommendations for Production

  • Use proper secrets management (e.g., AWS Secrets Manager)

  • Implement rate limiting

  • Add authentication for client connections

  • Use HTTPS for all external API calls

  • Regular security audits of dependencies

๐Ÿ“ˆ Dependencies

Core Dependencies

  • mcp[cli]==1.8.1 - Model Context Protocol framework

  • yfinance==0.2.61 - Yahoo Finance API wrapper

  • google-genai==1.15.0 - Google Gemini AI client

  • python-dotenv==1.1.0 - Environment variable management

  • pandas>=2.0.0 - Data processing and CSV handling

Development Dependencies

  • pytest>=7.0.0 - Testing framework

  • pytest-asyncio>=0.21.0 - Async testing support

  • black>=23.0.0 - Code formatting

  • mypy>=1.0.0 - Type checking

๐Ÿค Contributing

Development Setup

  1. Clone the repository

  2. Install development dependencies: pip install -r requirements.txt

  3. Run tests: pytest tests/

  4. Format code: black .

  5. Type check: mypy .

Code Quality Standards

  • All code must have type hints

  • Minimum 80% test coverage

  • Follow PEP 8 style guidelines

  • Comprehensive error handling

  • Detailed docstrings for all functions

๐Ÿ“„ License

This project is provided as-is for educational and development purposes. Please ensure compliance with all relevant APIs' terms of service when using in production.

๐Ÿ”„ Version History

v2.0.0 (Enhanced Version)

  • Added MCP resources and prompts

  • Comprehensive error handling and logging

  • Type safety and input validation

  • Configuration management

  • Testing suite

  • Enhanced documentation

v1.0.0 (Original Version)

  • Basic MCP server and client

  • Yahoo Finance integration

  • CSV fallback mechanism

  • AI-powered query understanding

-
security - not tested
F
license - not found
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI-powered natural language stock market queries with real-time data from Yahoo Finance and CSV fallback. Uses Google Gemini to interpret queries and automatically fetch stock prices, comparisons, and market summaries.

  1. ๐Ÿš€ Features
    1. Core Functionality
    2. Enhanced MCP Features
    3. Production-Ready Improvements
  2. ๐Ÿ“‹ Available Tools
    1. get_stock_price
    2. compare_stocks
    3. get_market_summary
  3. ๐Ÿ”ง MCP Resources
    1. stock_data
    2. market_info
  4. ๐ŸŽฏ MCP Prompts
    1. stock_analysis
    2. comparison_prompt
  5. ๐Ÿ—๏ธ Architecture
    1. Enhanced MCP Server (mcp_server.py)
    2. Enhanced MCP Client (mcp_client.py)
  6. ๐Ÿ“ฆ Installation
    1. Prerequisites
    2. Setup Steps
  7. ๐Ÿš€ Usage
    1. Starting the System
    2. Example Interactions
  8. ๐Ÿ“ Project Structure
    1. ๐Ÿงช Testing
      1. Running Tests
      2. Test Coverage
    2. โš™๏ธ Configuration
      1. Environment Variables
      2. CSV Data Format
    3. ๐Ÿ” Data Sources
      1. Primary: Yahoo Finance
      2. Fallback: Local CSV
    4. ๐Ÿ› Troubleshooting
      1. Common Issues
      2. Debug Mode
    5. ๐Ÿ“Š Performance Considerations
      1. Optimization Features
      2. Scalability Notes
    6. ๐Ÿ”’ Security Considerations
      1. Implemented Security Features
      2. Recommendations for Production
    7. ๐Ÿ“ˆ Dependencies
      1. Core Dependencies
      2. Development Dependencies
    8. ๐Ÿค Contributing
      1. Development Setup
      2. Code Quality Standards
    9. ๐Ÿ“„ License
      1. ๐Ÿ”„ Version History
        1. v2.0.0 (Enhanced Version)
        2. v1.0.0 (Original Version)

      MCP directory API

      We provide all the information about MCP servers via our MCP API.

      curl -X GET 'https://glama.ai/api/mcp/v1/servers/fjing1/MCP'

      If you have feedback or need assistance with the MCP directory API, please join our Discord server