📈 StockMCP

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

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

🛠️ 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 Léo Guerin

⭐ Star this repo | 🍴 Fork it | 📖 Docs