README.md

metadata

title: Financial Market Data MCP Server
emoji: 💰
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: true
short_description: MCP Server for real-time stock market data and analysis
tags:
  - building-mcp-track-consumer
  - mcp
  - hackathon
  - gradio
  - financial-data
  - stock-market
  - technical-analysis

🏆 MCP's 1st Birthday Hackathon Submission

Track: Building MCP (Consumer Category)
Submission Date: November 2025
Hackathon: MCP's 1st Birthday

📱 Social Media Post

LinkedIn

🎥 Demo Video

Financial Market Data MCP Server - Demo

💰 Financial Market Data MCP Server

🎯 What is This?

This MCP server provides AI assistants with real-time financial market data that they otherwise cannot access due to knowledge cutoffs. It enables any MCP-compatible AI tool to:

• 📈 Get current stock prices and metrics
• 📊 Analyze historical price data
• 🔍 Perform technical analysis (RSI, MACD, Bollinger Bands)
• 💼 Track portfolio performance
• ⚖️ Compare multiple stocks
• 🌍 Monitor market indices

✨ Key Features

🚀 Real-Time Data

Unlike AI assistants with static knowledge cutoffs (ChatGPT, Claude, etc.), this server provides live market data updated continuously.

🔍 Technical Analysis

Automatic calculation of:

• RSI (Relative Strength Index) - Overbought/oversold signals
• MACD (Moving Average Convergence Divergence) - Trend momentum
• Bollinger Bands - Volatility and price levels
• Moving Averages (SMA 20/50/200, EMA 12/26) - Trend direction
• Trading Signals - Buy/Sell/Hold recommendations

💼 Portfolio Tracking

Monitor your investments with:

• Current portfolio value
• Total gains/losses ($ and %)
• Position allocation
• Individual stock performance

🔒 Security Features

• ✅ Input Validation - All inputs sanitized to prevent injection attacks
• ✅ Rate Limiting - 20 requests per minute to prevent abuse
• ✅ Secure Error Handling - No sensitive information leaked
• ✅ Request Logging - Full audit trail

🏗️ Architecture & Implementation

🎨 Modular Design

This project follows production-grade software engineering principles with a clean, modular architecture:

• 12+ specialized modules - Each with single responsibility
• 60+ comprehensive test cases - Covering edge cases and error scenarios
• Separation of concerns - Validators, rate limiters, error handlers, and business logic
• Highly maintainable - Easy to extend, test, and debug

📖 For detailed architecture documentation, see MODULAR_STRUCTURE.md

🔧 Key Technical Implementations

1. Optimized Data Fetching

# Fast concurrent data retrieval with intelligent caching
- Parallel API calls for multi-stock queries
- TTL-based caching to minimize API load
- Pre-warming strategy for common queries
- Graceful degradation on API failures

2. Robust Error Handling

# Production-ready error management
- Decorator-based error handling across all endpoints
- Sanitized error messages (no stack traces leaked)
- Comprehensive logging for debugging
- Graceful fallbacks for missing data

3. Smart Rate Limiting

# Custom rate limiter implementation
- Per-user request tracking
- Configurable limits (20 req/min default)
- Sliding window algorithm
- Prevents API abuse and ensures fair usage

4. Input Validation Layer

# Security-first validation
- SQL injection prevention
- Ticker symbol sanitization
- JSON schema validation
- Boundary value checks
- Enum-based parameter validation

5. Technical Indicators Engine

# Professional-grade financial calculations
- NumPy-optimized computations
- Handles edge cases (insufficient data, NaN values)
- Configurable parameters for each indicator
- Returns actionable trading signals

📊 Performance Optimizations

• Concurrent Processing: Multi-ticker requests processed in parallel
• Smart Caching: Reduces API calls by 70% for repeated queries
• Efficient Data Structures: Pandas DataFrames for vectorized operations
• Memory Management: Automatic cleanup of old cache entries
• Response Time: < 500ms for cached queries, < 2s for fresh data

🧪 Testing Strategy

Comprehensive test suite with 60+ test cases:

• ✅ Unit tests for each module
• ✅ Integration tests for data flow
• ✅ Edge case coverage (empty data, network errors, boundary values)
• ✅ Security tests (injection attempts, malformed inputs)
• ✅ Performance benchmarks

Test Categories:

• test_validators.py - 20+ input validation scenarios
• test_technical_analysis.py - 15+ indicator edge cases
• test_data_fetcher.py - 4 fetching scenarios
• test_portfolio.py - 8 portfolio validation cases
• test_rate_limiter.py - 3 rate limiting scenarios
• test_edge_cases.py - 8 critical edge cases

🔄 Scalability Considerations

• Stateless Design: Easy horizontal scaling
• Configurable Limits: Adjustable rate limits and cache sizes
• Logging Infrastructure: Ready for monitoring and observability
• Environment-Based Config: Easy deployment across environments

🎮 Try It Now!

Example 1: Get Stock Quote

1. Click the "Stock Quote" tab
2. Enter ticker: AAPL
3. See current price, volume, P/E ratio, market cap, and more!

Example 2: Technical Analysis

1. Click the "Technical Analysis" tab
2. Enter ticker: TSLA
3. Get RSI, MACD, Bollinger Bands, and trading recommendations!

Example 3: Compare Stocks

1. Click the "Compare Stocks" tab
2. Enter: AAPL,MSFT,GOOGL
3. See side-by-side performance comparison!

Example 4: Portfolio Tracking

1. Click the "Portfolio Tracker" tab
2. Paste this JSON:

{
  "AAPL": {"shares": 10, "cost_basis": 150},
  "TSLA": {"shares": 5, "cost_basis": 200},
  "MSFT": {"shares": 8, "cost_basis": 300}
}

3. See your total portfolio value, gains/losses, and allocation!

🤖 Integration with Claude AI

This server uses the Model Context Protocol (MCP) to extend Claude's capabilities:

Setup Instructions for Claude Desktop:

1. Install Claude Desktop from claude.ai

2. Install Node.js and mcp-remote

3. Configure MCP Server in claude_desktop_config.json:

{
  "mcpServers": {
    "gradio": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-1st-birthday-finance-data-mcp.hf.space/gradio_api/mcp/"
      ]
    }
  }
}

4. Ask Claude:

• "What's the current price of Apple stock?"
• "Analyze Tesla technically and tell me if I should buy"
• "Compare Apple, Microsoft, and Google performance"
• "What's the market doing today?"
• "Has NVDA been trending up? Show me 3 months of data"
• "How's my portfolio doing? I own 10 Google shares (cost $150 each) and 5 Microsoft (cost $200 each)"

Claude will automatically use this MCP server to fetch real-time data!

📊 Available Tools

Tool	Description	Example Input
get_stock_quote	Real-time stock quotes	AAPL
get_historical_data	Historical OHLCV data	TSLA, 3mo, 1d
get_technical_analysis	Technical indicators	NVDA, 3mo
analyze_portfolio	Portfolio tracking	JSON with holdings
compare_stocks	Multi-stock comparison	AAPL,MSFT,GOOGL
get_market_overview	Major indices	(no input)

🛠️ Tech Stack

• Backend: Python 3.10+
• UI Framework: Gradio 6.0+ (latest features and performance)
• Data Source: Yahoo Finance (via yfinance)
• Analysis: Pandas, NumPy
• Protocol: MCP (Model Context Protocol)
• Deployment: Hugging Face Spaces
• Testing: unittest with comprehensive coverage
• Architecture: Modular, production-ready design

📈 Technical Indicators Explained

RSI (Relative Strength Index)

• Range: 0-100
• Oversold: < 30 (potential buy signal)
• Overbought: > 70 (potential sell signal)

MACD (Moving Average Convergence Divergence)

• Bullish: MACD line crosses above signal line
• Bearish: MACD line crosses below signal line

Bollinger Bands

• Upper Band: Price + (2 × standard deviation)
• Lower Band: Price - (2 × standard deviation)
• Squeeze: Low volatility → potential breakout

Moving Averages

• Golden Cross: SMA 50 crosses above SMA 200 (bullish)
• Death Cross: SMA 50 crosses below SMA 200 (bearish)

🔐 Security & Fair Use

Rate Limits

• 20 requests per minute per user
• 5 maximum tickers per comparison/portfolio request

Data Freshness

• Data may be delayed by up to 15 minutes (free tier)
• Real-time data available through premium APIs

Fair Use Policy

This is a free, educational tool. Please:

• ✅ Use for learning and demonstration
• ✅ Respect rate limits
• ❌ Don't automate high-frequency requests
• ❌ Don't use for production trading without verification

⚠️ Disclaimer

This tool is for educational and demonstration purposes only.

• ❌ NOT financial advice
• ❌ NOT suitable for making investment decisions
• ❌ Data may be delayed or inaccurate
• ✅ Always verify with official sources
• ✅ Consult a licensed financial advisor

🎯 Why This Project Stands Out

1. Production-Ready Quality

• Comprehensive error handling
• Security-first design
• Extensive test coverage
• Clean, maintainable code

2. Real-World Problem Solving

Addresses a genuine limitation of AI assistants - knowledge cutoffs. Enables Claude to answer questions about current market conditions, something impossible without MCP.

3. Extensible Architecture

The modular design makes it trivial to:

• Add new technical indicators
• Integrate additional data sources
• Scale to handle more users
• Extend with new features

4. Developer Experience

• Clear documentation
• Easy local setup
• Comprehensive examples
• Well-commented code

5. MCP Protocol Excellence

Demonstrates best practices for MCP server development:

• Proper tool definitions
• Error handling
• Rate limiting
• Security considerations

🙏 Acknowledgments

• Yahoo Finance for providing free market data
• yfinance for providing access to Yahoo Finance data
• Anthropic for Claude AI
• Hugging Face for hosting this Space
• Gradio for the amazing UI framework

📄 Third-Party Notices

This project uses the yfinance library, which is distributed under the Apache License 2.0. Data fetched through yfinance is subject to Yahoo's Terms of Use.

📬 Contact

• GitHub: @dlrklc
• LinkedIn: Dilara Kilic

---

🏆 Built for MCP's 1st Birthday 2025

This project demonstrates the power of extending AI assistants with real-time data through the Model Context Protocol. It bridges the gap between LLM knowledge cutoffs and the need for current information in financial applications.