StockMCP

# 📈 StockMCP > **A comprehensive Model Context Protocol (MCP) server for real-time stock market data using Yahoo Finance** [](https://www.python.org/downloads/) [](https://fastapi.tiangolo.com/) [](https://opensource.org/licenses/MIT) [](#testing) 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`: ```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](https://www.alphavantage.co/support/#api-key) 2. **Configure environment**: ```bash # 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) ```bash # 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 ```bash # 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: ```json { "mcpServers": { "stock-mcp": { "command": "npx", "args": [ "mcp-remote", "http://localhost:3001/mcp", "--header", "--allow-http" ] } } } ``` #### Cursor Add to your MCP configuration: ```json { "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 ```bash # 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 ```bash # 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: ```bash # 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](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](https://github.com/leogue/StockMCP/issues) - 💡 **Feature Requests** - [Start a discussion](https://github.com/leogue/StockMCP/discussions) - 📖 **Documentation** - Check our comprehensive API docs - 💬 **Community** - Join our discussions for help and ideas --- <div align="center"> **Made with ❤️ for the financial data community by [Léo Guerin](https://www.leoguerin.fr/)** [⭐ Star this repo](https://github.com/leogue/StockMCP) | [🍴 Fork it](https://github.com/leogue/StockMCP/fork) | [📖 Docs](https://github.com/leogue/StockMCP/wiki) </div>