StockMCP is a Python-based MCP server that provides a JSON-RPC 2.0 interface for real-time stock market data via Yahoo Finance (yfinance) with optional Alpha Vantage integration. Once started, it exposes an HTTP endpoint at http://localhost:3001/mcp (or your configured host/port) and offers a discovery/interaction model via MCP tools. Clients can query available tools with a tools/list-like operation and execute specific tools with tools/call, enabling real-time quotes, fundamentals, price history, dividends/actions, analyst forecasts, and growth projections. This makes it suitable for AI apps, trading bots, or financial analysis tools that rely on standardized, discoverable MCP interfaces.

To integrate with clients like Claude Desktop or other MCP-compliant frontends, point them to the endpoint /mcp and use the provided tools list to discover capabilities. The server documents its API and interactive docs at /docs when running, and it supports JSON-RPC 2.0 over HTTP for tool execution and metadata discovery.

Prerequisites:

• Python 3.10+ installed
• Git installed
• Optional: Docker if you prefer containerized deployment

1. Clone the repository: git clone https://github.com/your-username/StockMCP.git cd StockMCP

2. Create and activate a Python virtual environment (recommended): python -m venv venv source venv/bin/activate # on macOS/Linux .\venv\Scripts\activate # on Windows

3. Install dependencies: pip install -e .

   or if a requirements file exists:

   pip install -r requirements.txt

4. Configure environment variables (example):

   • Create .env and add: LOG_LEVEL=INFO HOST=0.0.0.0 PORT=3001 ALPHAVANTAGE_KEY=your-api-key (if using Alpha Vantage features)

5. Run the server directly: python src/main.py

   Server will run at http://localhost:3001/mcp by default

6. Optional Docker deployment: docker build -t stockmcp . docker run -p 3001:3001 --env-file .env stockmcp

7. Testing with a client:

   • Discover tools via tools/list
   • Execute a tool with tools/call and appropriate parameters

Notes:

• If you only need a quick start, you can also run the server with uv (as shown in development docs) and then switch to the standard Python runtime as needed.

Tips and common considerations:

• Data sources: Primary data comes from Yahoo Finance via yfinance. Alpha Vantage can be enabled for enhanced earnings estimates and forecasts; an API key is required for extended features.
• Environment variables: LOG_LEVEL, HOST, PORT, and ALPHAVANTAGE_KEY can be tuned for your deployment. Consider adding caching and retry logic for production use.
• Networking: By default the server binds to 0.0.0.0:3001. Open firewall rules accordingly if hosting publicly.
• API usage: While free Yahoo Finance data is suitable for many use cases, be mindful of rate limits and plan for caching or fallback strategies in high-demand scenarios.
• Documentation: Interactive docs are available at http://localhost:3001/mcp/docs when running. Use tools/list to discover available tools and tools/call to invoke them.