Metadata-Version: 2.4
Name: curistat-mcp
Version: 0.1.1
Summary: Futures volatility intelligence MCP server for ES, NQ, and related products
Project-URL: Homepage, https://curistat.com
Project-URL: Documentation, https://curistat.com/developer
Project-URL: Repository, https://github.com/moxiespirit/curistat-mcp
Project-URL: Issues, https://github.com/moxiespirit/curistat-mcp/issues
Author-email: Curistat <dev@curistat.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ES,NQ,curistat,futures,mcp,model-context-protocol,trading,volatility
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Description-Content-Type: text/markdown

# Curistat MCP Server

[![MCP Server](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io/)
[![Glama](https://glama.ai/mcp/servers/moxiespirit/curistat-mcp/badge)](https://glama.ai/mcp/servers/moxiespirit/curistat-mcp)
[![PyPI](https://img.shields.io/pypi/v/curistat-mcp)](https://pypi.org/project/curistat-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Futures-specific volatility intelligence for AI agents via the [Model Context Protocol](https://modelcontextprotocol.io/).

The first MCP server dedicated to futures volatility analytics. Provides forecasts, regime detection, rare signals, directional bias, and research tools for ES, NQ, and related products.

## Quick Start

### 1. Install

```bash
pip install curistat-mcp
```

### 2. Get a Curistat API key

Sign up at [curistat.com/developer](https://curistat.com/developer) and generate an API key.

### 3. Configure Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "curistat": {
      "command": "python",
      "args": ["-m", "curistat_mcp"],
      "env": {
        "CURISTAT_API_KEY": "cst_agent_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. You can now ask Claude questions like:
- "What's the volatility forecast for ES today?"
- "Are there any rare signals firing for NQ?"
- "Show me the economic calendar for next week"
- "Find historical days similar to today for ES"

## Available Tools

### Core Intelligence

| Tool | Description |
|------|-------------|
| `get_forecast_today` | Daily volatility forecast (1-10 rating) with expected move ranges |
| `get_forecast_week` | 5-day forward volatility forecast |
| `get_signals` | Scan all 24 rare volatility signals |
| `get_direction` | Directional bias (17-component aggregate) |
| `get_session_plan` | Full session planner with trade setups |

### Regime

| Tool | Description |
|------|-------------|
| `get_regime` | CRC composite (0-100, 5 bands) |
| `get_pulse` | Market conditions snapshot |

### Research

| Tool | Description |
|------|-------------|
| `get_calendar` | Economic calendar with vol impact estimates |
| `get_event_impact` | Historical vol analysis around specific events |
| `get_similar_days` | Historical analog day lookup |

### Supported Products

`ES`, `NQ`, `MES`, `MNQ`, `SPX`, `SPY`, `QQQ`

## Agent Framework Integration

### CrewAI

```python
from crewai import Agent
from crewai_tools import MCPTool

curistat_tools = MCPTool(
    server_command="python",
    server_args=["-m", "curistat_mcp"],
    server_env={"CURISTAT_API_KEY": "cst_agent_..."},
)

analyst = Agent(
    role="Futures Volatility Analyst",
    tools=[curistat_tools],
    goal="Analyze market conditions and provide trading intelligence",
)
```

### LangChain

```python
from langchain_mcp import MCPToolkit

toolkit = MCPToolkit(
    server_command="python",
    server_args=["-m", "curistat_mcp"],
    server_env={"CURISTAT_API_KEY": "cst_agent_..."},
)

tools = toolkit.get_tools()
```

### Direct stdio (any MCP client)

```bash
CURISTAT_API_KEY=cst_agent_... python -m curistat_mcp
```

The server communicates via stdio using the MCP protocol.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `CURISTAT_API_KEY` | Yes | -- | Your Curistat Developer API key |
| `CURISTAT_API_URL` | No | `https://api.curistat.com` | API base URL |

## Rate Limits

Rate limits are enforced by your API key tier, not by the MCP server. The server is a thin client that proxies requests to the Curistat API.

| Tier | Requests/min | Requests/day |
|------|-------------|-------------|
| Free | 10 | 100 |
| Pro | 60 | 5,000 |
| Agent | 120 | 50,000 |

## License

[MIT](LICENSE)
