Overview

Chronulus AI MCP Server lets you run Chronulus forecasting and prediction agents inside any Model Context Protocol (MCP)–aware client (for example, Claude for Desktop). It turns your time-series data into explainable forecasts, visualizations, and actionable recommendations by exposing Chronulus model capabilities as MCP tools. Use it to integrate forecasting workflows directly into chat-driven agent flows and interactive sessions.

This server is intended for developers who want to embed forecasting agents into tool-enabled assistants. Once configured in your MCP client, the Chronulus MCP Server will accept data inputs, run forecasting pipelines on Chronulus, return plots and textual explanations, and support dataset upload and model selection flows — enabling rapid experimentation and production-ready forecasting inside a chat-based interface.

Features

Exposes Chronulus forecasting capabilities as MCP-accessible agents
Upload and ingest time-series datasets from files or URLs
Generate forecasts with confidence intervals and exportable plots
Return textual “Chronulus Explanation” alongside visualizations
Integrates with MCP ecosystems (Claude Desktop, other MCP clients)
Container-friendly (Docker) and installable via pip / PyPI
Works alongside other MCP servers (filesystem, fetch, etc.) to create end-to-end workflows

Installation / Configuration

Supported installation methods: pip (PyPI), directly from GitHub, Docker, and uvx. You must provide your Chronulus API key via environment variable CHRONULUS_API_KEY.

Prerequisites:

Python 3.8+ (if using pip)
Docker (if using Docker)
An MCP-capable client (e.g., Claude for Desktop)

Config file locations

Platform	Claude config path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Install from PyPI (recommended)

pip install chronulus-mcp

Install from GitHub

git clone https://github.com/ChronulusAI/chronulus-mcp.git
cd chronulus-mcp
pip install .

Run as a Python module (example)

python -m chronulus_mcp
# ensure CHRONULUS_API_KEY is present in your environment
export CHRONULUS_API_KEY="sk_XXXX..."

Docker build and run

git clone https://github.com/ChronulusAI/chronulus-mcp.git
cd chronulus-mcp
docker build . -t chronulus-mcp

# in Claude config, run this image:
# docker run -i --rm -e CHRONULUS_API_KEY chronulus-mcp

uvx (package runner) usage (if you use uvx)

{
  "mcpServers": {
    "chronulus-agents": {
      "command": "uvx",
      "args": ["chronulus-mcp"],
      "env": {
        "CHRONULUS_API_KEY": "<YOUR_CHRONULUS_API_KEY>"
      }
    }
  }
}

Claude Desktop MCP server entry example

{
  "mcpServers": {
    "chronulus-agents": {
      "command": "python",
      "args": ["-m", "chronulus_mcp"],
      "env": {
        "CHRONULUS_API_KEY": "<YOUR_CHRONULUS_API_KEY>"
      }
    }
  }
}

Notes and troubleshooting

If you see errors like “spawn python ENOENT”, provide the absolute path to your python binary (e.g., /usr/bin/python3).
If using uvx or docker, ensure those binaries are installed and available in PATH, or use absolute paths.
Always set CHRONULUS_API_KEY in the environment forwarded to the MCP process.

Available Tools / Resources

When registered with an MCP client, the Chronulus MCP Server typically provides tools to:

Upload datasets (CSV, Parquet, or other supported formats)
Trigger forecast runs on selected models and horizons
Retrieve forecast results and confidence intervals
Generate plots (PNG/SVG) for embedding in chat
Return a text explanation of model behavior and forecast drivers (“Chronulus Explanation”)

You can combine these with third-party MCP servers (filesystem, fetch) to build richer workflows: fetch remote data, persist datasets, and visualize outputs inside the client.

Example of combining Chronulus with filesystem and fetch in Claude config:

{
  "mcpServers": {
    "chronulus-agents": { "command": "uvx", "args": ["chronulus-mcp"], "env": { "CHRONULUS_API_KEY": "<KEY>" } },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/AIWorkspace"] },
    "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] }
  }
}

Use Cases

Retail demand forecasting: Upload historical SKU-level sales data and generate weekly forecasts with confidence bands to inform purchase orders and inventory safety stock.
Capacity planning: Forecast resource utilization (CPU, memory, bandwidth) from time-series telemetry and produce actionable scaling recommendations with visualizations and explanations.
Financial time-series: Produce short-term forecasts for cash flow, revenue, or trading signals; include model explanations to document drivers and assumptions.
Supply chain anomaly detection: Combine fetch + Chronulus to pull external datasets (shipments, lead times) and generate forecasts to spot deviations and trigger alerts.

Example developer workflow

Configure Chronulus MCP in your Claude client with CHRONULUS_API_KEY.
Use a filesystem server to load a historical CSV of daily sales.
Invoke the Chronulus forecast tool to request a 12-week horizon.
Receive a plot image, the forecast table, and a Chronulus Explanation in-chat.
Iterate on model settings or upload additional features as needed.

Where to get it

Source, releases, and issues: https://github.com/ChronulusAI/chronulus-mcp

For MCP client configuration details, see the Model Context Protocol docs: https://modelcontextprotocol.io/quickstart/user

Chronulus AI MCP Server for Forecasting Agents