📌Overview

Purpose: The MCP Server for Chronulus enables users to interact with Chronulus AI forecasting and prediction agents within the Claude desktop environment.

Overview: This framework provides installation and configuration options for seamless integration with Claude for Desktop, allowing users to easily communicate with AI forecasting agents. It supports multiple installation methods, including pip, Docker, and uvx, and can be used alongside additional third-party servers for enhanced functionality.

Key Features:

Flexible Installation Options: Users can choose to install the framework using pip, Docker, or uvx, making it accessible based on individual preferences and technical capabilities.
Comprehensive Configuration Support: Detailed configuration instructions are provided to streamline the setup process, including environment variable management for API keys and the configuration of additional servers.

MCP Server for Chronulus

Chat with Chronulus AI Forecasting & Prediction Agents in Claude.

Quickstart: Claude for Desktop

Install

Claude for Desktop is currently available on macOS and Windows.

Install Claude for Desktop here:
https://claude.ai/download

Configuration

Follow the general instructions at https://modelcontextprotocol.io/quickstart/user to configure the Claude desktop client.

Your Claude config file can be found at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Choose one of the following methods to add chronulus-mcp to your claude_desktop_config.json.

Using pip

Option 1: Install release from PyPI

pip install chronulus-mcp

Option 2: Install from Github

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

Add this configuration to claude_desktop_config.json:

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

Note: If you get an error like "MCP chronulus-agents: spawn python ENOENT", provide the absolute path to python.
Example: /Library/Frameworks/Python.framework/Versions/3.11/bin/python3 instead of python.

Using Docker

Build a docker image called 'chronulus-mcp':

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

Add this configuration to claude_desktop_config.json (ensure the image name matches):

{
  "mcpServers": {
    "chronulus-agents": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "CHRONULUS_API_KEY", "chronulus-mcp"],
      "env": {
        "CHRONULUS_API_KEY": "<YOUR_CHRONULUS_API_KEY>"
      }
    }
  }
}

Using uvx

uvx will pull, install, and run the latest version of chronulus-mcp.

Add this configuration to claude_desktop_config.json:

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

Note: If you get an error like "MCP chronulus-agents: spawn uvx ENOENT", then either:

Install uvx (instructions: https://docs.astral.sh/uv/getting-started/installation/) or

Provide the absolute path to uvx, e.g. /Users/username/.local/bin/uvx.

Additional Servers (Filesystem, Fetch, etc)

In demos, third-party servers like fetch and filesystem are also used. See their documentation for installation and configuration.

Example configuration to run filesystem and fetch servers alongside Chronulus in claude_desktop_config.json:

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

Claude Preferences

To streamline your experience using Claude across tools, add your preferences under Claude Settings.

You can upgrade your Claude preferences from:

Claude Desktop: Settings -> General -> Claude Settings -> Profile (tab)
Web: https://claude.ai/settings (Profile tab)

Preferences are shared between Claude Desktop and claude.ai.

Below are preferences used in demos:

## Tools-Dependent Protocols
The following instructions apply only when tools/MCP Servers are accessible.

### Filesystem - Tool Instructions
- Do not use 'read_file' or 'read_multiple_files' on binary files (e.g., images, pdfs, docx).
- When working with binary files, use 'get_info' instead of 'read_*' tools to inspect files.

### Chronulus Agents - Tool Instructions
- Prefer input field types like TextFromFile, PdfFromFile, and ImageFromFile over scanning files directly.
- When plotting forecasts from Chronulus, always include the Chronulus-provided forecast explanation below the plot labeled as "Chronulus Explanation".

chronulus-mcp