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

Parameter	Type	Required	Default	Description
ds	array[string]	✅ Yes	—	List of dates in ISO format (YYYY-MM-DD)
y	array[number]	✅ Yes	—	List of numeric values aligned with ds
periods	integer	No	10	Number of future periods to forecast
lower_limit	number	No	—	Flag forecast values below this threshold
upper_limit	number	No	—	Flag forecast values above this threshold

Output Columns

Column	Meaning
ds	Date for the observed or predicted value
yhat	Predicted value (model's best estimate)
yhat_lower	Lower bound of confidence interval (worst-case)
yhat_upper	Upper bound of confidence interval (best-case)
status	✅ OK, ⚠️ EXCEEDS UPPER, or ⚠️ BELOW LOWER (only when limits are set)

Understanding the Two Types of Bounds

	yhat_lower / yhat_upper	lower_limit / upper_limit
Set by	Prophet model (automatic)	You (manual)
Purpose	Statistical confidence range	Business rule enforcement
Answers	"How sure is the model?"	"Is the forecast safe for my business?"
Example	"Revenue will be 800–1200"	"Our warehouse can't handle > 1000 orders"

---

📂 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

Package	Purpose
flask	Web server framework
pandas	Data manipulation
prophet	Time-series forecasting engine
requests	HTTP client (examples only)

---

📄 License

MIT License

---

👥 Contributing

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

Author: Pradeep Chandra Kalahasthi
Original Base: sendgrid-mcp