📈 StockMCP

Name: StockMCP
Author: leogue

A comprehensive Model Context Protocol (MCP) server for real-time stock market data using Yahoo Finance

Python 3.10+ FastAPI License: MIT Tests

StockMCP provides a powerful, JSON-RPC 2.0 compliant interface for accessing comprehensive stock market data, built on the Model Context Protocol standard. Perfect for AI applications, financial analysis tools, and trading bots.

🌐 Free Hosted Endpoint

Use StockMCP immediately without any setup! We provide a free hosted endpoint at:

Endpoint: https://stockmcp.leoguerin.fr/mcp
No API key required - Just add to your MCP client configuration

Claude Desktop Configuration

For immediate access, use this configuration in your claude_desktop_config.json:

{ "mcpServers": { "stock-mcp": { "command": "npx", "args": [ "mcp-remote", "https://stockmcp.leoguerin.fr/mcp", "--header", "--allow-http" ] } } }

Configuration file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Related MCP server: YFinance Trader MCP Tool

🛠️ Available Tools

Tool Name	Description
`get_realtime_quote`	Retrieve current market data including price, volume, market cap, and key financial ratios
`get_fundamentals`	Access comprehensive financial statements (income, balance sheet, cash flow) and calculated ratios
`get_price_history`	Get historical OHLCV data with optional total return calculation including reinvested dividends
`get_dividends_and_actions`	Analyze dividend payment history and corporate actions with quality metrics and consistency scoring
`get_analyst_forecasts`	Get analyst price targets, consensus ratings (Buy/Hold/Sell), and EPS forecasts from professional analysts
`get_growth_projections`	Forward growth projections for revenue, earnings (EPS), and free cash flow with 1-year, 3-year, and 5-year CAGR estimates

🚀 Quick Start

API Key Setup

Get a free Alpha Vantage API key: Visit https://www.alphavantage.co/support/#api-key
Configure environment:
# Copy the example environment file cp .env.example .env # Edit .env and add your API key ALPHAVANTAGE_KEY=your-actual-api-key-here

Using Docker (Recommended)

# Clone the repository git clone https://github.com/yourusername/StockMCP.git cd StockMCP # Configure your API key (see API Key Setup above) cp .env.example .env # Edit .env with your Alpha Vantage API key # Build and run with Docker docker build -t stockmcp . docker run -p 3001:3001 --env-file .env stockmcp

Local Development

# Install dependencies with uv (fastest) uv sync # Or with pip pip install -e . # Configure your API key (see API Key Setup above) cp .env.example .env # Edit .env with your Alpha Vantage API key # Run the server python src/main.py # Server runs on http://localhost:3001/mcp

MCP Client Integration

Once your server is running, integrate it with MCP clients:

Claude Desktop

Edit the configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{ "mcpServers": { "stock-mcp": { "command": "npx", "args": [ "mcp-remote", "http://localhost:3001/mcp", "--header", "--allow-http" ] } } }

Cursor

Add to your MCP configuration:

{ "stock-mcp": { "command": "npx", "args": [ "mcp-remote", "http://localhost:3001/mcp", "--header", "--allow-http" ] } }

Other MCP Clients

For any MCP-compatible client, use:

Endpoint: http://localhost:3001/mcp
Protocol: JSON-RPC 2.0 over HTTP
Tools: Available via tools/list method

🔗 Usage

StockMCP implements the Model Context Protocol (MCP) for seamless integration with AI applications. Once running, the server provides:

Endpoint: http://localhost:3001/mcp
Protocol: JSON-RPC 2.0 over HTTP
Discovery: Use tools/list to get available tools
Execution: Use tools/call to execute tools with parameters

For detailed API examples and JSON schemas, access the interactive documentation at http://localhost:3001/mcp/docs when the server is running.

🛠️ Development

Project Structure

StockMCP/ ├── src/ │ ├── main.py # FastAPI server and endpoints │ ├── models.py # Pydantic models for MCP and stock data │ ├── mcp_handlers.py # MCP protocol request handlers │ ├── tools.py # Tools package entry point │ └── tools/ # Modular tools implementation │ ├── market_data.py # Real-time quotes, history, fundamentals │ ├── analysis.py # Forecasts and growth projections │ └── registry.py # Tool registration and execution ├── tests/ # Comprehensive test suite (100 tests) ├── Dockerfile # Container configuration ├── pyproject.toml # Project dependencies and configuration └── README.md # This file

Running Tests

# Run all tests uv run pytest # Run with verbose output uv run pytest -v # Run specific test file uv run pytest tests/test_api.py # Run with coverage uv run pytest --cov=src

Dependencies

Core Dependencies:

FastAPI - Modern web framework for APIs
Pydantic - Data validation using Python type hints
yfinance - Yahoo Finance data retrieval (primary data source)
pandas - Data manipulation and analysis
scipy - Scientific computing (required by yfinance)

Development Dependencies:

pytest - Testing framework
httpx - HTTP client for testing
pytest-mock - Mocking utilities

🐳 Docker Deployment

Build and Run

# Build the image docker build -t stockmcp . # Run the container docker run -p 3001:3001 stockmcp # Run in background docker run -d -p 3001:3001 --name stockmcp-server stockmcp

Environment Configuration

The container exposes the API on port 3001 by default. You can customize this:

# Custom port mapping docker run -p 8080:3001 stockmcp # With environment variables docker run -p 3001:3001 -e LOG_LEVEL=DEBUG stockmcp

🔧 Configuration

Server Configuration

The server can be configured through environment variables:

LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR)
HOST - Server host (default: 0.0.0.0)
PORT - Server port (default: 3001)

API Limits & Data Sources

Primary Data Source: Yahoo Finance (yfinance)

Free tier with reasonable rate limits
Real-time and historical data
No API key required for basic usage

Secondary Data Source: Alpha Vantage (optional)

Enhanced earnings estimates and forecasts
Requires free API key for extended features
Graceful fallback when unavailable

Production Recommendations:

Implement request caching
Add retry logic with exponential backoff
Monitor API usage patterns
Consider data source redundancy

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with proper tests
Run the test suite (uv run pytest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Type Hints - All functions should have proper type annotations
Tests - New features must include comprehensive tests
Documentation - Update README and docstrings for any API changes
Code Style - Follow PEP 8 and use meaningful variable names

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Yahoo Finance - For providing free stock market data
Model Context Protocol - For the excellent protocol specification
FastAPI - For the amazing web framework
Pydantic - For robust data validation

📞 Support

🐛 Bug Reports - Open an issue
💡 Feature Requests - Start a discussion
📖 Documentation - Check our comprehensive API docs
💬 Community - Join our discussions for help and ideas

Made with ❤️ for the financial data community by

⭐ Star this repo | 🍴 Fork it | 📖 Docs

StockMCP