Chronulus AI

<div align="center">
<img width="150px" src="https://www.chronulus.com/brand-assets/chronulus-logo-blue-on-alpha-square.png" alt="Chronulus AI">
    <h1 align="center">Unleash Chronulus AI Forecasting in Claude via MCP</h1>
    <h3 align="center">Seamlessly Integrate Chronulus Prediction Agents with Claude's Desktop Interface</h3>
</div>

## Elevate Your Claude Experience with Chronulus AI Forecasting

This guide provides a comprehensive walkthrough on integrating Chronulus AI's powerful forecasting and prediction agents into your Claude desktop environment using the Model Context Protocol (MCP). By leveraging MCP, you can seamlessly connect Claude with Chronulus, enabling advanced AI-driven insights directly within your chat interface.

### Prerequisites

*   **Claude for Desktop:** Ensure you have Claude for Desktop installed. It's currently available for macOS and Windows. Download it [here](https://claude.ai/download).
*   **Chronulus API Key:** You'll need a valid Chronulus API key to authenticate your requests.

### Configuration: Connecting Claude to Chronulus

The following steps outline how to configure Claude for Desktop to communicate with the Chronulus MCP server.

1.  **Locate Claude Configuration:** Find your `claude_desktop_config.json` file.
    *   **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    *   **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

2.  **Choose Your Installation Method:** Select the method that best suits your technical expertise and environment. We provide options for `pip`, `docker`, and `uvx`.

#### Method 1: Using pip (Recommended for Python Developers)

This method leverages Python's package installer, `pip`, to install and run the Chronulus MCP server.

*   **Option 1: Install from PyPI (Stable Release)**

    ```bash
    pip install chronulus-mcp
    ```

*   **Option 2: Install from GitHub (Latest Development Version)**

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

*   **Configure `claude_desktop_config.json`:** Add the following configuration to your `claude_desktop_config.json` file:

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

    **Troubleshooting:** If you encounter an error like "MCP chronulus-agents: spawn python ENOENT," you likely need to provide the absolute path to your Python executable. For example: `/Library/Frameworks/Python.framework/Versions/3.11/bin/python3`.

#### Method 2: Using Docker (Recommended for Containerized Environments)

This method utilizes Docker to containerize the Chronulus MCP server, providing a consistent and isolated environment.

*   **Build the Docker Image:**

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

*   **Configure `claude_desktop_config.json`:**

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

    **Important:** Ensure the image name in the `docker run` command matches the name you assigned during the build process.

#### Method 3: Using uvx (Recommended for Simplified Execution)

`uvx` simplifies the process by automatically fetching, installing, and running the Chronulus MCP server from the PyPI registry.

*   **Configure `claude_desktop_config.json`:**

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

    **Troubleshooting:** If you encounter an error like "MCP chronulus-agents: spawn uvx ENOENT," ensure that `uv` is installed and accessible in your system's PATH. You can either:

    1.  Install `uv`: Follow the instructions [here](https://docs.astral.sh/uv/getting-started/installation/).
    2.  Provide the absolute path to `uvx`. For example: `/Users/username/.local/bin/uvx`.

### Enhancing Functionality with Additional MCP Servers

To further augment your Claude experience, consider integrating other MCP servers like `fetch` and `filesystem`.

*   **`fetch`:** Enables Claude to retrieve data from URLs.
*   **`filesystem`:** Grants Claude access to your local file system.

Refer to the documentation provided by the respective server maintainers for detailed installation and configuration instructions.

**Example Configuration:**

```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"]
    }
  }
}

Optimizing Claude's Behavior with Preferences

Fine-tune Claude's behavior to seamlessly interact with the integrated tools by setting preferences within Claude's settings. These preferences are shared across both Claude for Desktop and Claude.ai (the web interface).

Access Claude's settings:

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

Recommended Preferences:

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

By following these steps, you can unlock the full potential of Chronulus AI forecasting within your Claude environment, enabling data-driven decision-making and enhanced AI workflows.