Prophet MCP Server

An open-source Model Context Protocol (MCP) server engineered for Time-Series Forecasting.

Powered by Meta's Prophet, this server enables LLMs to generate accurate forecasts, trend analyses, and confidence intervals from historical data — turning raw numbers into actionable insights within AI workflows.

Note: This project is a specialized fork of the sendgrid-mcp server, re-engineered to provide robust forecasting capabilities via the MCP protocol.

🚀 Key Capabilities

1. Predictive Modeling

Leverages Meta's Prophet to predict future trends based on historical data. Handles seasonality, outliers, and trend changes automatically.

2. LLM-Friendly Output

Returns data in a format optimized for Large Language Models:

• Plain-English Summaries: Instant context on trends (e.g., "Trending UPWARD by +51.7%").
• Statistical Breakdowns: Historical vs. Forecasted means, min/max, standard deviations.
• Chart.js Config: Ready-to-render visualization config for web deployment.

3. Bounds Validation

Optional upper/lower limits to flag out-of-bounds forecasts — turning predictions into decision-support with business-rule enforcement.

4. Interactive Visualization

Includes Chart.js configuration in every response with:

• Red dots for actual historical data
• Dashed blue line for forecast predictions
• Shaded confidence interval band
• Red/orange dashed limit lines (when bounds are set)

📖 How It Works

┌─────────────────────────────────────────────────────────────┐
│  1. LLM sends your historical data (dates + values)        │
│  2. Prophet model learns the pattern                        │
│  3. Server generates forecast for N future periods          │
│  4. Response includes:                                      │
│     ├── Human-readable summary with trend analysis          │
│     ├── Forecast data table (with optional bounds status)   │
│     └── Chart.js config for instant visualization           │
└─────────────────────────────────────────────────────────────┘

📊 Real-World Example

Let's say you tracked daily website conversions over 10 days and want to forecast the next 5 days — with a safety limit of max 22 conversions (your team can't handle more).

Input

{
  "ds": ["2025-01-01", "2025-01-02", "2025-01-03", "2025-01-04", "2025-01-05",
         "2025-01-06", "2025-01-07", "2025-01-08", "2025-01-09", "2025-01-10"],
  "y": [10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
  "periods": 5,
  "upper_limit": 22
}

Output

### Prophet Forecast Data ###

Summary of forecast metrics:
  - Historical Period: 2025-01-01 to 2025-01-10
  - Historical Data Points: 10
  - Historical Mean: 14.50
  - Forecast Periods: 5
  - Trend Direction: UPWARD (+51.7% vs historical mean)

Bounds Validation:
  - Upper Limit: 22
  - ⚠️ 2 date(s) OUT OF BOUNDS:
    2025-01-14: yhat=23.00 > upper_limit=22
    2025-01-15: yhat=24.00 > upper_limit=22

Key Takeaway: The model predicts the values will trend upward over the next
5 periods, with predicted values ranging from 20.00 to 24.00.

Date       | yhat  | yhat_lower | yhat_upper | Status
----------------------------------------------------
2025-01-01 | 10.00 | 10.00      | 10.00      | ✅ OK
...
2025-01-14 | 23.00 | 23.00      | 23.00      | ⚠️ EXCEEDS UPPER
2025-01-15 | 24.00 | 24.00      | 24.00      | ⚠️ EXCEEDS UPPER

chartjs = { ... }

No data-science expertise required. The output tells you the trend direction, flags risky dates, and provides visualization config — all in plain text.

🛠️ Tool: forecast_time_series

Description

Ingests time-series data and returns a future forecast with a detailed text summary, bounds validation, and Chart.js visualization config.

Input Parameters

Output Columns

Understanding the Two Types of Bounds

📂 Project Structure

Prophet_mcp/
├── app.py                  # Flask server — MCP endpoint, auth, JSON-RPC routing
├── mcp_helper.py           # Core engine — Prophet forecasting, summary, Chart.js config
├── requirements.txt        # Python dependencies
├── README.md               # This file
├── .gitignore              # Git exclusions
└── examples/               # Local testing utilities (not required for deployment)
    ├── plot_forecast.py    # Script to call API and generate a local HTML chart
    └── forecast_chart.html # Auto-generated preview (gitignored)

📦 Installation & Setup

Prerequisites

• Anaconda or Miniconda (recommended for Prophet dependencies)
• Python 3.11+

1. Environment Setup

# Create environment
conda create -n prophet-mcp python=3.11
conda activate prophet-mcp

# Install dependencies
pip install -r requirements.txt

Windows Users: Prophet requires CmdStan. If you encounter issues, refer to the Prophet Installation Guide or install via conda: conda install -c conda-forge prophet.

2. Configuration

The server uses Bearer Token authentication. Set the MCP_TOKEN environment variable, or it defaults to the value in app.py:

# Set your token (recommended for production)
export MCP_TOKEN="your-secure-token-here"

🏃‍♂️ Running the Server

python app.py

• Server URL: http://localhost:3000
• MCP Endpoint: POST http://localhost:3000/mcp

Authentication

All requests must include the header:

Authorization: Bearer <your-token>

Example API Call (cURL)

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: `MCP_TOKEN` \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "forecast_time_series",
      "arguments": {
        "ds": ["2025-01-01","2025-01-02","2025-01-03","2025-01-04","2025-01-05",
               "2025-01-06","2025-01-07","2025-01-08","2025-01-09","2025-01-10"],
        "y": [10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
        "periods": 5,
        "upper_limit": 22
      }
    },
    "id": 1
  }'

🧪 Testing & Visualization

Local Testing Script

python examples/plot_forecast.py

This script will:

1. Call your MCP server's API
2. Extract the Chart.js config from the response
3. Generate forecast_chart.html with an interactive chart
4. Open it in your default browser

The generated chart features a dark glassmorphism theme with:

• 🔴 Red dots — Historical actuals
• 🔵 Dashed blue line — Forecast predictions
• 🟦 Shaded blue band — Confidence interval
• 🔴 Red dashed line — Upper limit (if set)
• 🟠 Orange dashed line — Lower limit (if set)

☁️ Cloud Deployment

For deploying to Google Cloud (or any cloud provider), you only need:

app.py
mcp_helper.py
requirements.txt

The examples/ folder is for local testing only and is not required in production.

🔐 Security

• Bearer Token authentication on all endpoints
• Token configurable via MCP_TOKEN environment variable
• JSON-RPC error handling with proper error codes
• Input validation on all tool parameters

📄 Dependencies

📄 License

MIT License

👥 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author: Pradeep Chandra Kalahasthi
Original Base: sendgrid-mcp