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. Growth Model Selection

Choose the right forecasting model for your scenario:

• Linear (default): Unbounded straight-line trend — ideal for metrics with no natural ceiling.

• Logistic (S-curve): Saturating growth that respects a cap (max) and optional floor (min) — ideal for metrics like market share, adoption rates, or capacity-limited systems.

3. Multi-Frequency Forecasting

Supports daily, hourly, weekly, and monthly time series via the freq parameter — use the frequency that matches your input data.

4. LLM-Friendly Output

Returns data in a structured, two-part format optimized for Large Language Models:

• content[0] — Text Summary: Plain-English analysis with trend direction (e.g., "UPWARD +26.1%"), statistical breakdowns, growth model details, and a full forecast data table.

• content[1] — Chart.js Config: A proper JSON payload (chartjs_config:{...}) ready for visualization — no regex parsing needed.

5. Premium Interactive Visualization

Every response includes a Chart.js configuration with:

• 🟣 Indigo gradient confidence band (shaded between upper/lower bounds)

• 🔵 Solid blue fitted line for historical model fit

• 🔵 Dashed blue forecast line with diamond markers for future predictions

• 🔴 Coral actuals with white-bordered circle markers

• 📍 Vertical "Forecast →" annotation marking where predictions begin

• 🔴 Red/🟠 orange dashed cap/floor lines for logistic growth

• 🌙 Premium dark theme with glassmorphism styling

6. Robust Error Handling

Input validation with clear error messages for:

• Empty or mismatched data arrays

• Invalid growth model values

• Missing cap for logistic growth

• Invalid floor >= cap combinations

📖 How It Works

┌─────────────────────────────────────────────────────────────┐
│  1. LLM sends historical data (dates + values) via MCP     │
│  2. User selects growth model (linear or logistic)          │
│  3. Prophet model learns patterns and generates forecast    │
│  4. Response contains two content items:                    │
│     ├── content[0]: Human-readable summary + data table     │
│     └── content[1]: Chart.js JSON config for visualization  │
└─────────────────────────────────────────────────────────────┘

📊 Response Format

The MCP tools/call response returns two content items:

content[0] — Text Summary

### Prophet Forecast Data ###

Growth model used: LOGISTIC (cap=120, floor=30)

Summary of forecast metrics:
  - Historical Period: 2025-02-01 to 2025-03-02
  - Trend Direction: UPWARD (+26.1% vs historical mean)

Date | yhat | yhat_lower | yhat_upper
-------------------------------------
2025-03-03 | 79.56 | 76.93 | 81.98
...

content[1] — Chart.js JSON

chartjs_config:{"type":"line","data":{"labels":[...],"datasets":[...]},"options":{...}}

This is valid JSON prefixed with chartjs_config: — parse it as:

cfg_json = content[1]["text"][len("chartjs_config:"):]
config = json.loads(cfg_json)

🛠️ Tool: forecast_time_series

Input Parameters

When to Use Each Growth Model

Output Columns

📂 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
├── Procfile                     # Cloud deployment (gunicorn)
├── README.md                    # This file
├── .gitignore                   # Git exclusions
└── examples/                    # Local testing utilities (not required for deployment)
    ├── plot_forecast.py         # Basic forecast test with Chart.js visualization
    └── test_gcp_marketing.py    # Real-world marketing scenario (30-day conversions)

📦 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:

# Set your token (required)
export MCP_TOKEN="your-secure-token-here"

🏃‍♂️ Running the Server

Local Development

MCP_TOKEN="your-token" python app.py

Production (Cloud)

gunicorn app:app

• Server URL: http://localhost:3000

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

• Health Check: GET /health

Environment Variables

Authentication

All /mcp 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: Bearer <your-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,
        "growth": "logistic",
        "cap": 25,
        "floor": 5
      }
    },
    "id": 1
  }'

🧪 Testing & Visualization

Basic Test

MCP_TOKEN="your-token" python examples/plot_forecast.py

Marketing Forecast Test (30-day real-world scenario)

MCP_TOKEN="your-token" python examples/test_gcp_marketing.py

Both scripts will:

1. Call your MCP server's API

2. Extract the Chart.js config from content[1]

3. Generate an interactive HTML chart with premium dark theme

4. Open it in your default browser

☁️ Cloud Deployment

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

app.py
mcp_helper.py
requirements.txt
Procfile

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

The server binds to 0.0.0.0 and reads the PORT environment variable automatically for cloud compatibility.

🔐 Security

• Bearer Token authentication on all /mcp endpoints

• Token configurable via MCP_TOKEN environment variable (no defaults — must be explicitly set)

• Debug mode disabled by default (enable via MCP_DEBUG=true)

• JSON-RPC error handling with proper error codes

• Input validation on all tool parameters

• No sensitive data stored in source code

📄 Dependencies

📄 License

MIT License

👥 Contributing

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

Author: Pradeep Chandra Kalahasthi
Original Base: sendgrid-mcp