Skip to main content
Glama

StockMCP

by leogue
GitHub
Python
2
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

📈 StockMCP

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

🛠️ 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

  1. Get a free Alpha Vantage API key: Visit https://www.alphavantage.co/support/#api-key

  2. 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:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Make your changes with proper tests

  4. Run the test suite (uv run pytest)

  5. Commit your changes (git commit -m 'Add amazing feature')

  6. Push to the branch (git push origin feature/amazing-feature)

  7. 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

This server cannot be installed

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

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Provides real-time stock market data and financial analysis through Yahoo Finance integration. Enables users to get quotes, historical prices, fundamentals, dividends, analyst forecasts, and growth projections for any stock symbol.

  1. 🌐 Free Hosted Endpoint
    1. Claude Desktop Configuration
  2. 🛠️ Available Tools
    1. 🚀 Quick Start
      1. API Key Setup
      2. Using Docker (Recommended)
      3. Local Development
      4. MCP Client Integration
    2. 🔗 Usage
      1. 🛠️ Development
        1. Project Structure
        2. Running Tests
        3. Dependencies
      2. 🐳 Docker Deployment
        1. Build and Run
        2. Environment Configuration
      3. 🔧 Configuration
        1. Server Configuration
        2. API Limits & Data Sources
      4. 🤝 Contributing
        1. Development Guidelines
      5. 📝 License
        1. 🙏 Acknowledgments
          1. 📞 Support

            Related MCP Servers

            • MCP Stock Analysis Server

              giptilabs
              -
              security
              F
              license
              -
              quality
              Provides access to real-time and historical Indian stock data via Yahoo Finance API, enabling local LLMs to retrieve stock information through MCP-compatible agents like Claude Desktop and Cursor.
              Last updated -
              2

            • Finance MCP Server

              dino65-dev
              -
              security
              A
              license
              -
              quality
              Provides real-time financial data from Yahoo Finance to Large Language Models through the Model Context Protocol, enabling AI models to access stock prices, historical data, and company information.
              Last updated -
              MIT License

            • Yahoo Finance MCP Server

              16Coffee
              A
              security
              A
              license
              A
              quality
              A Model Context Protocol server providing comprehensive financial data from Yahoo Finance, allowing users to retrieve detailed stock information, financial statements, options data, and market news.
              Last updated -
              34
              MIT License
              • Apple

            View all related MCP servers

            Appeared in Searches

            New MCP Servers

            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/leogue/StockMCP'

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