Stock-Prediction-MCP-Server

artembatyr/Stock-Prediction-MCP-Server

3.1

If you are the rightful owner of Stock-Prediction-MCP-Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Stock Prediction MCP Server is a model context protocol server designed to fetch stock data and generate AI-powered trading reports using the Massive.com (Polygon.io) API.

Tools
2
Resources
0
Prompts
0

Stock Prediction MCP Server

An MCP (Model Context Protocol) server for stock prediction using the Massive.com (Polygon.io) API. This server provides tools to fetch stock data and generate AI-powered trading reports.

Features

  • Fetch stock data for one or more tickers
  • Generate AI-powered stock performance reports
  • Configurable date ranges for historical data
  • Docker containerization support
  1. Artem - created github repo and published image to dockerhub, corrections
  2. Ha - created docker settings and made mcp server working out of the box on Linux and Windows systems.
  3. Nihad - documented the project and discribed everything in README.md and described how to setup claude desktop.
  4. Omar - created basic arhitecture diagram which illustrate the components, interactions, and data flow and created claude_desktop_config example
  5. Domma - implemented the next functions and main logic of mcp server in service.py - generate_ai_report, get_stock_data, generate_stock_report and document for windows setup
  6. Caroline - implemented the next functions and main logic of mcp server: fetch_stock_data_for_tickers, fetch_stock_data_for_ticker, get_date_range, get_date_n_days_ago and document for windows setup.

Arhitecture diagram ┌─────────────────────────────────────────────────────────────────────────────┐ │ USER INTERACTION LAYER │ └─────────────────────────────────────────────────────────────────────────────┘ │ │ User prompts/queries │ (e.g., "Get stock data for TSLA") ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ CLAUDE DESKTOP APPLICATION │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ Location: │ │ │ │ • macOS: ~/Library/Application Support/Claude/ │ │ │ │ • Windows: %APPDATA%\Claude\ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ Configuration: claude_desktop_config.json │ │ │ │ { │ │ │ │ "mcpServers": { │ │ │ │ "stock-prediction": { │ │ │ │ "command": "docker", │ │ │ │ "args": ["run", "-i", "--rm", │ │ │ │ "-e", "POLYGON_API_KEY=xxx", │ │ │ │ "artbfh/stock-prediction-mcp:latest"] │ │ │ │ } │ │ │ │ } │ │ │ │ } │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ │ │ MCP Protocol (stdio) │ Tool calls via JSON-RPC ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ DOCKER CONTAINER LAYER │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ Image: artbfh/stock-prediction-mcp:latest │ │ │ │ Platform: linux/amd64, linux/arm64 (multi-platform) │ │ │ │ Base: python:3.13-slim │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ Environment Variables │ │ │ • POLYGON_API_KEY (runtime) │ │ ▼ │ ┌─────────────────────────────────────────────────────────────────────────────┐ │ MCP SERVER (FastMCP Framework) │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ File: service.py │ │ │ │ Framework: FastMCP │ │ │ │ Transport: stdio │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ INITIALIZATION │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ │ │ 1. Read POLYGON_API_KEY from environment │ │ │ │ │ │ 2. Initialize RESTClient(polygon_api_key) │ │ │ │ │ │ 3. Register MCP tools with @mcp.tool() decorator │ │ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ MCP TOOLS (Exposed to Claude Desktop) │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │ │ │ │ Tool 1: │ │ Tool 2: │ │ Tool 3: │ │ │ │ │ │ get_stock_data │ │ generate_ │ │ get_stock_ │ │ │ │ │ │ │ │ stock_report │ │ summary │ │ │ │ │ │ Input: │ │ │ │ │ │ │ │ │ │ • tickers (str) │ │ Input: │ │ Input: │ │ │ │ │ │ • days_back (int)│ │ • tickers (str) │ │ • ticker (str) │ │ │ │ │ │ • end_days_back │ │ • days_back (int)│ │ • days_back (int)│ │ │ │ │ │ │ │ • end_days_back │ │ │ │ │ │ │ │ Output: │ │ │ │ Output: │ │ │ │ │ │ Raw stock data │ │ Output: │ │ Performance │ │ │ │ │ │ (formatted str) │ │ AI-ready prompt │ │ summary │ │ │ │ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ INTERNAL HELPER FUNCTIONS │ │ │ │ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ │ │ Date Utilities: │ │ Data Fetching: │ │ │ │ │ │ • format_date() │ │ • fetch_stock_data_ │ │ │ │ │ │ • get_date_n_days_ago│ │ for_ticker() │ │ │ │ │ │ • get_date_range() │ │ • fetch_stock_data_ │ │ │ │ │ └──────────────────────┘ │ for_tickers() │ │ │ │ │ └──────────────────────┘ │ │ │ │ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ │ │ AI Report Generation:│ │ Data Processing: │ │ │ │ │ │ • generate_ai_report()│ │ • Parse ticker list │ │ │ │ │ └──────────────────────┘ │ • Format responses │ │ │ │ │ └──────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ │ │ HTTP/HTTPS REST API │ Polygon.io API Client │ (polygon-api-client library) ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ POLYGON.IO / MASSIVE.COM API │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ Endpoint: https://api.polygon.io │ │ │ │ Authentication: API Key (POLYGON_API_KEY) │ │ │ │ │ │ │ │ API Calls: │ │ │ │ • GET /v2/aggs/ticker/{ticker}/range/{multiplier}/{timespan}/ │ │ │ │ {from}/{to} │ │ │ │ │ │ │ │ Response Data: │ │ │ │ { │ │ │ │ "results": [ │ │ │ │ { │ │ │ │ "t": timestamp, │ │ │ │ "o": open_price, │ │ │ │ "h": high_price, │ │ │ │ "l": low_price, │ │ │ │ "c": close_price, │ │ │ │ "v": volume │ │ │ │ } │ │ │ │ ] │ │ │ │ } │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────

Data Flow

Example: User requests stock data for TSLA

USER INPUT └─> "Get stock data for TSLA" │ ▼ CLAUDE DESKTOP └─> Parses request └─> Identifies need for MCP tool: get_stock_data └─> Reads claude_desktop_config.json └─> Executes: docker run -e POLYGON_API_KEY=xxx artbfh/stock-prediction-mcp:latest │ ▼ DOCKER CONTAINER └─> Starts container └─> Runs: uv run python service.py └─> Initializes FastMCP server └─> Reads POLYGON_API_KEY from environment └─> Creates RESTClient(api_key) │ ▼ MCP PROTOCOL (stdio) └─> Claude Desktop sends JSON-RPC request: { "method": "tools/call", "params": { "name": "get_stock_data", "arguments": { "tickers": "TSLA", "days_back": 3, "end_days_back": 1 } } } │ ▼ MCP SERVER (service.py) └─> @mcp.tool() get_stock_data() receives call └─> Calls get_date_range(3, 1) └─> Returns: ("2024-01-20", "2024-01-22") └─> Calls fetch_stock_data_for_tickers(["TSLA"], "2024-01-20", "2024-01-22") └─> For each ticker: └─> Calls fetch_stock_data_for_ticker("TSLA", ...) └─> Executes async: polygon_client.list_aggs(...) │ ▼ POLYGON.IO API └─> HTTP GET Request: GET /v2/aggs/ticker/TSLA/range/1/day/2024-01-20/2024-01-22 Headers: Authorization: Bearer {POLYGON_API_KEY} │ ▼ └─> Returns JSON response with stock aggregates │ ▼ DATA PROCESSING └─> Parse API response └─> Format data: "Stock data for TSLA: 2024-01-20: Open=$250.00, High=$255.00, Low=$248.00, Close=$252.00, Volume=1000000 2024-01-21: Open=$252.00, High=$258.00, Low=$251.00, Close=$256.00, Volume=1200000 2024-01-22: Open=$256.00, High=$260.00, Low=$254.00, Close=$258.00, Volume=1100000" │ ▼ MCP RESPONSE └─> Returns formatted string to Claude Desktop via stdio │ ▼ CLAUDE DESKTOP └─> Receives response └─> Formats and displays to user │ ▼ USER SEES RESULT └─> "Here's the stock data for TSLA over the last 3 days..."

Component interactions

1. Claude Desktop – where the user works. It sends MCP tool calls to your server.
2. MCP Docker container – runs the FastMCP stock prediction server (artbfh/stock-prediction-mcp:latest). It exposes tools such as get_stock_data and generate_stock_report.
3. Polygon/Massive.com APIs – the MCP server calls these APIs (using the provided API key) to fetch historical stock data.

Setup

Prerequisites

  • Python 3.13+
  • uv (Python package manager)
  • Docker (optional, for containerization)
  • Polygon.io API key (get one at https://polygon.io/)

Installation

  1. Install dependencies:
uv sync
  1. Set your API key as an environment variable:
export POLYGON_API_KEY="your_api_key_here"
# OR
export MASSIVE_API_KEY="your_api_key_here"

Running Locally

uv run python service.py

Docker

Using Docker Hub (Recommended)

On Windows (PowerShell/CMD), macOS, or Linux:

Pull the pre-built image from Docker Hub:

docker pull artbfh/stock-prediction-mcp:latest

If you encounter a platform error on Windows, explicitly specify the platform:

docker pull --platform linux/amd64 artbfh/stock-prediction-mcp:latest

Run the container:

docker run -e POLYGON_API_KEY="your_api_key_here" artbfh/stock-prediction-mcp:latest

Windows Requirements:

  • Install Docker Desktop for Windows
  • Make sure Docker Desktop is running before pulling or running containers
  • The commands work the same in PowerShell, Command Prompt, or Git Bash
  • The image supports both linux/amd64 (Windows/Intel) and linux/arm64 (Apple Silicon) platforms
Building Locally

Build the Docker image locally:

docker build -t stock-prediction-mcp .

Run the container:

docker run -e POLYGON_API_KEY="your_api_key_here" stock-prediction-mcp
Publishing to Docker Hub

To publish your own version to Docker Hub:

  1. Make sure you're logged in:
docker login
  1. Build and push using the provided script:
./build-and-push.sh <your-dockerhub-username> [version]

Example:

./build-and-push.sh myusername latest
./build-and-push.sh myusername 1.0.0

Claude Desktop Configuration

Important: You need Claude Desktop installed to use this MCP server. The Docker container is just the server - Claude Desktop is the client that connects to it.

Prerequisites

  1. Install Claude Desktop:

  2. Install Docker Desktop (if using Docker option):

  3. Pull the Docker image (if using Docker option):

    docker pull artbfh/stock-prediction-mcp:latest

Configuration Steps

Add the following to your Claude Desktop configuration file:

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

Note: On Windows, %APPDATA% typically resolves to C:\Users\YourUsername\AppData\Roaming\Claude\

Option 1: Using Docker (from Docker Hub)

For Windows, macOS, and Linux:

{
  "mcpServers": {
    "stock-prediction": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "POLYGON_API_KEY=your_api_key_here",
        "artbfh/stock-prediction-mcp:latest"
      ]
    }
  }
}

Important Notes:

  • Make sure Docker Desktop is installed and running before using this configuration
  • Claude Desktop will automatically start the Docker container when you use the MCP tools
  • You don't need to manually run docker run - Claude Desktop handles it
  • Replace your_api_key_here with your actual Polygon.io API key

Option 2: Using uv directly

On macOS/Linux:

{
  "mcpServers": {
    "stock-prediction": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/weather",
        "python",
        "service.py"
      ],
      "env": {
        "POLYGON_API_KEY": "your_api_key_here"
      }
    }
  }
}

On Windows:

{
  "mcpServers": {
    "stock-prediction": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "C:\\path\\to\\weather",
        "python",
        "service.py"
      ],
      "env": {
        "POLYGON_API_KEY": "your_api_key_here"
      }
    }
  }
}

Replace the path with the absolute path to this project directory. On Windows, use backslashes (\\) or forward slashes (/) - both work.

Available Tools

get_stock_data

Fetches stock data for one or more tickers.

Parameters:

  • tickers (string): Comma-separated list of ticker symbols (e.g., "TSLA,AAPL,META")
  • days_back (int, optional): Number of days back for start date (default: 3)
  • end_days_back (int, optional): Number of days back for end date (default: 1)

Example:

get_stock_data(tickers="TSLA,AAPL", days_back=3, end_days_back=1)

generate_stock_report

Generates a stock performance report with AI-powered analysis.

Parameters:

  • tickers (string): Comma-separated list of ticker symbols (e.g., "TSLA,AAPL,META")
  • days_back (int, optional): Number of days back for start date (default: 3)
  • end_days_back (int, optional): Number of days back for end date (default: 1)

Example:

generate_stock_report(tickers="TSLA,AAPL", days_back=3, end_days_back=1)

Usage in Claude Desktop

Once configured, you can ask Claude to:

  • "Get stock data for TSLA and AAPL"
  • "Generate a stock report for META, TSLA, and AAPL"
  • "What's the stock performance for the last 5 days for TSLA?"

Claude will automatically use the MCP tools to fetch the data and provide analysis.

Docker Hub

This MCP server is available on Docker Hub as a public repository:

  • Image: artbfh/stock-prediction-mcp:latest
  • Pull command: docker pull artbfh/stock-prediction-mcp:latest

Using the Docker Hub Image

On Windows (PowerShell or Command Prompt)
  1. Pull the image:
docker pull artbfh/stock-prediction-mcp:latest

Note: If you get a platform error, Docker will automatically select the correct platform. If needed, you can explicitly specify:

docker pull --platform linux/amd64 artbfh/stock-prediction-mcp:latest
  1. Test the image (optional - just to verify it works):
docker run -e POLYGON_API_KEY="your_api_key_here" artbfh/stock-prediction-mcp:latest

Note: This command will start the MCP server and it will wait for input. You can press Ctrl+C to stop it. This is just for testing - in normal use, Claude Desktop will automatically start and manage the container.

  1. Install and configure Claude Desktop (required):
    • Download and install Claude Desktop for Windows
    • Configure Claude Desktop to use the Docker image (see "Claude Desktop Configuration" section below)
    • Claude Desktop will automatically start the Docker container when needed
On macOS/Linux
  1. Pull the image:
docker pull artbfh/stock-prediction-mcp:latest
  1. Test the image (optional - just to verify it works):
docker run -e POLYGON_API_KEY="your_api_key_here" artbfh/stock-prediction-mcp:latest

Note: This command will start the MCP server and it will wait for input. You can press Ctrl+C to stop it. This is just for testing - in normal use, Claude Desktop will automatically start and manage the container.

Configure Claude Desktop (Required)

Configure Claude Desktop to use the Docker Hub image (see Claude Desktop Configuration section above)

Note: The Docker commands work the same on Windows, macOS, and Linux. You can use either PowerShell or Command Prompt on Windows.

Notes

  • The API key is required for all operations and must be passed at runtime
  • Stock data is fetched from Polygon.io (used by Massive.com)
  • Default date range is 3 days back to 1 day back (yesterday)
  • The server uses stdio transport for MCP communication
  • Security: Never hardcode API keys in Docker images. Always pass them as environment variables at runtime.