# 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](https://github.com/garethcull/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
```json
{
"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
```text
### 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](https://www.anaconda.com/download) or Miniconda (recommended for Prophet dependencies)
- Python 3.11+
### 1. Environment Setup
```bash
# 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](https://facebook.github.io/prophet/docs/installation.html) 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`:
```bash
# Set your token (recommended for production)
export MCP_TOKEN="your-secure-token-here"
```
---
## 🏃♂️ Running the Server
```bash
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)
```bash
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
```bash
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](https://github.com/garethcull/sendgrid-mcp)
