MCP Server for Chronulus

1<div align="center">
2<img width="150px" src="https://www.chronulus.com/brand-assets/chronulus-logo-blue-on-alpha-square.png" alt="Chronulus AI">
3    <h1 align="center">MCP Server for Chronulus</h1>
4    <h3 align="center">Chat with Chronulus AI Forecasting & Prediction Agents in Claude</h3>
5</div>
6 
7 
8 
9 
10### Quickstart: Claude for Desktop
11 
12#### Install 
13 
14Claude for Desktop is currently available on macOS and Windows.
15 
16Install Claude for Desktop [here](https://claude.ai/download)
17 
18#### Configuration
19 
20Follow the general instructions [here](https://modelcontextprotocol.io/quickstart/user) to configure the Claude desktop client.
21 
22You can find your Claude config at one of the following locations:
23 
24- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
25- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
26 
27Then choose one of the following methods that best suits your needs and add it to your `claude_desktop_config.json`
28 
29 
30 
31<details>
32<summary>Using pip</summary>
33 
34(Option 1) Install release from PyPI
35 
36```bash 
37pip install chronulus-mcp
38```
39 
40 
41(Option 2) Install from Github
42 
43```bash 
44git clone https://github.com/ChronulusAI/chronulus-mcp.git
45cd chronulus-mcp
46pip install .
47```
48 
49 
50 
51```json 
52{
53  "mcpServers": {
54    "chronulus-agents": {
55      "command": "python",
56      "args": ["-m", "chronulus_mcp"],
57      "env": {
58        "CHRONULUS_API_KEY": "<YOUR_CHRONULUS_API_KEY>"
59      }
60    }
61  }
62}
63```
64 
65Note, if you get an error like "MCP chronulus-agents: spawn python ENOENT", 
66then you most likely need to provide the absolute path to `python`. 
67For example `/Library/Frameworks/Python.framework/Versions/3.11/bin/python3` instead of just `python`
68 
69</details>
70 
71 
72<details>
73<summary>Using docker</summary>
74 
75Here we will build a docker image called 'chronulus-mcp' that we can reuse in our Claude config.
76 
77```bash 
78git clone https://github.com/ChronulusAI/chronulus-mcp.git
79cd chronulus-mcp
80 docker build . -t 'chronulus-mcp'
81```
82 
83In your Claude config, be sure that the final argument matches the name you give to the docker image in the build command.
84 
85```json 
86{
87  "mcpServers": {
88    "chronulus-agents": {
89      "command": "docker",
90      "args": ["run", "-i", "--rm", "-e", "CHRONULUS_API_KEY", "chronulus-mcp"],
91      "env": {
92        "CHRONULUS_API_KEY": "<YOUR_CHRONULUS_API_KEY>"
93      }
94    }
95  }
96}
97```
98 
99</details>
100 
101<details>
102<summary>Using uvx</summary>
103 
104`uvx` will pull the latest version of `chronulus-mcp` from the PyPI registry, install it, and then run it.
105 
106 
107```json 
108{
109  "mcpServers": {
110    "chronulus-agents": {
111      "command": "uvx",
112      "args": ["chronulus-mcp"],
113      "env": {
114        "CHRONULUS_API_KEY": "<YOUR_CHRONULUS_API_KEY>"
115      }
116    }
117  }
118}
119```
120 
121Note, if you get an error like "MCP chronulus-agents: spawn uvx ENOENT", then you most likely need to either:
1221. [install uv](https://docs.astral.sh/uv/getting-started/installation/) or
1232. Provide the absolute path to `uvx`. For example `/Users/username/.local/bin/uvx` instead of just `uvx`
124 
125</details>
126 
127#### Additional Servers (Filesystem, Fetch, etc)
128 
129In our demo, we use third-party servers like [fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) and [filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem).
130 
131For details on installing and configure third-party server, please reference the documentation provided by the server maintainer.
132 
133Below is an example of how to configure filesystem and fetch alongside Chronulus in your `claude_desktop_config.json`: 
134 
135```json 
136{
137  "mcpServers": {
138    "chronulus-agents": {
139      "command": "uvx",
140      "args": ["chronulus-mcp"],
141      "env": {
142        "CHRONULUS_API_KEY": "<YOUR_CHRONULUS_API_KEY>"
143      }
144    },
145    "filesystem": {
146      "command": "npx",
147      "args": [
148        "-y",
149        "@modelcontextprotocol/server-filesystem",
150        "/path/to/AIWorkspace"
151      ]
152    },
153    "fetch": {
154      "command": "uvx",
155      "args": ["mcp-server-fetch"]
156    }
157  }
158} 
159```
160 
161 
162#### Claude Preferences
163 
164To streamline your experience using Claude across multiple sets of tools, it is best to add your preferences to under Claude Settings. 
165 
166You can upgrade your Claude preferences in a couple ways:
167 
168* From Claude Desktop: `Settings -> General -> Claude Settings -> Profile (tab)`
169* From [claude.ai/settings](https://claude.ai/settings): `Profile (tab)`
170 
171Preferences are shared across both Claude for Desktop and Claude.ai (the web interface). So your instruction need to work across both experiences.
172 
173Below are the preferences we used to achieve the results shown in our demos:
174 
175```
176## Tools-Dependent Protocols
177The following instructions apply only when tools/MCP Servers are accessible.
178 
179### Filesystem - Tool Instructions
180- Do not use 'read_file' or 'read_multiple_files' on binary files (e.g., images, pdfs, docx) .
181- When working with binary files (e.g., images, pdfs, docx) use 'get_info' instead of 'read_*' tools to inspect a file.
182 
183### Chronulus Agents - Tool Instructions
184- When using Chronulus, prefer to use input field types like TextFromFile, PdfFromFile, and ImageFromFile over scanning the files directly.
185- When plotting forecasts from Chronulus, always include the Chronulus-provided forecast explanation below the plot and label it as Chronulus Explanation.
186```