Chronulus MCP Server

What is Chronulus MCP Server about?

Chronulus MCP Server exposes Chronulus AI forecasting and prediction agents through the Model Context Protocol, allowing Claude (desktop or web) to invoke forecasting tools, retrieve explanations, and work with various file types.

How to use Chronulus MCP Server?

1. Install the server via pip, Docker, or uvx.
2. Add a server entry to claude_desktop_config.json with the appropriate command and environment variable CHRONULUS_API_KEY.
3. Restart Claude; the server appears as chronulus-agents and can be called from prompts.

Key Features

• Multiple installation methods (pip, Docker, uvx) for flexible environments.
• Supports text, PDF, and image input types via specialized Chronulus field types.
• Returns forecast visualizations together with Chronulus‑provided explanations.
• Works alongside other MCP servers such as filesystem and fetch.
• Provides clear guidance on handling binary files.

Use Cases

• Generating economic or weather forecasts directly within a conversational AI workflow.
• Automating report generation that includes plotted forecasts and explanatory notes.
• Integrating Chronulus forecasting capabilities with existing tools like file system browsers or web fetchers.

FAQ

Q: Which command should I use if I get ENOENT errors? A: Ensure the full path to the executable (python, uvx, etc.) is provided, or install the missing tool.

Q: Can I run the server on Windows? A: Yes. Use the Docker method or install via pip/uvx; configure the Windows config path %APPDATA%\Claude\claude_desktop_config.json.

Q: Do I need to install additional servers? A: Only if your workflow requires them (e.g., filesystem or fetch). They can be added to the same config file.

Q: How do I supply my API key? A: Set CHRONULUS_API_KEY in the env section of the server entry or expose it as an environment variable on the host.

Quickstart: Claude for Desktop

Install

Claude for Desktop is currently available on macOS and Windows.

Install Claude for Desktop here

Configuration

Follow the general instructions here to configure the Claude desktop client.

You can find your Claude config at one of the following locations:

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

Then choose one of the following methods that best suits your needs and add it to your claude_desktop_config.json

(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 .

{
  "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", then you most likely need to provide the absolute path to python. For example /Library/Frameworks/Python.framework/Versions/3.11/bin/python3 instead of just python

Here we will build a docker image called 'chronulus-mcp' that we can reuse in our Claude config.

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

In your Claude config, be sure that the final argument matches the name you give to the docker image in the build command.

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

uvx will pull the latest version of chronulus-mcp from the PyPI registry, install it, and then run it.

{
  "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 you most likely need to either:

1. install uv or
2. Provide the absolute path to uvx. For example /Users/username/.local/bin/uvx instead of just uvx

Additional Servers (Filesystem, Fetch, etc)

In our demo, we use third-party servers like fetch and filesystem.

For details on installing and configure third-party server, please reference the documentation provided by the server maintainer.

Below is an example of how to configure filesystem and fetch alongside Chronulus in your 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 multiple sets of tools, it is best to add your preferences to under Claude Settings.

You can upgrade your Claude preferences in a couple ways:

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

Preferences are shared across both Claude for Desktop and Claude.ai (the web interface). So your instruction need to work across both experiences.

Below are the preferences we used to achieve the results shown in our 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 (e.g., images, pdfs, docx) use 'get_info' instead of 'read_*' tools to inspect a file.

### Chronulus Agents - Tool Instructions
- When using Chronulus, prefer to use input field types like TextFromFile, PdfFromFile, and ImageFromFile over scanning the files directly.
- When plotting forecasts from Chronulus, always include the Chronulus-provided forecast explanation below the plot and label it as Chronulus Explanation.