ichi-mcp

A minimal Model Context Protocol (MCP) stdio server, built on the official Python mcp SDK, that lets an AI assistant read the free public ICHI API. No API key is needed.

What ICHI is (and is not)

ICHI — the Internet Cyber Health Index — is a free, publicly accessible, source-transparent daily barometer of internet-wide cyber threat conditions, created by Joe Bernik. It is an outside-in directional signal. It is not an organization-specific risk score, not a deterministic forecast, and not a substitute for your own internal telemetry. The band is the operative read; moves within a band should be treated as noise. See the methodology.

This repository is maintained by/for ICHI's creator.

Related MCP server: winfolio

Tools

Every tool returns a JSON object with "ok": true, or "ok": false plus an "error" message on timeouts, HTTP errors, or unparseable responses — the server never crashes on a bad upstream response.

Install / run

Requires Python ≥ 3.10. With uv:

uvx --from git+https://github.com/bernik-bot/ichi-mcp ichi-mcp

Pin a release with git+https://github.com/bernik-bot/ichi-mcp@v0.1.0. Or with pip: pip install git+https://github.com/bernik-bot/ichi-mcp then run ichi-mcp. (Not published on PyPI.)

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ichi": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/bernik-bot/ichi-mcp", "ichi-mcp"]
    }
  }
}

If uvx isn't on Claude Desktop's PATH, use its absolute path (which uvx).

Generic MCP client (stdio)

{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/bernik-bot/ichi-mcp", "ichi-mcp"],
  "env": { "ICHI_TIMEOUT": "10" }
}

Configuration

Example output (abridged, from a live call)

{
  "ok": true,
  "score": 64.91,
  "rounded": 65,
  "band": "ELEVATED",
  "band_range": "50-69",
  "evaluated_at": "2026-10-31T13:30:22.978Z",
  "model": "v7.1",
  "dimensions": [
    {"key": "V", "name": "Vulnerability Pressure", "score": 42.21, "contribution": 8},
    {"key": "C", "name": "C2 / Malware Infrastructure", "score": 96.03, "contribution": 13.14}
  ],
  "freshness": {"headline_state": "LIVE", "age_seconds": 267, "completeness": "COMPLETE", "stale_inputs": [], "impaired_sources": []},
  "link": "https://ichi.global"
}

Limitations

• Reads only ICHI's public endpoints; it does no scoring of its own and adds no data.

• Dimension names are mapped from API keys using the published methodology (model v7.x). The API key P is the phishing-driven dimension the methodology labels "O — Actor Operations"; the informational O value is labelled as Outages. Unknown keys are passed through unchanged. If ICHI's schema changes, missing fields come back as null rather than errors.

• The alerts feed is ICHI's critical-advisory RSS feed; per its own description it is observation only and carries no score.

• No caching: each tool call makes one HTTP request. ICHI's current index is re-evaluated about every 10 minutes.

Development

uv venv && uv pip install -e ".[dev]"
ruff check . && pytest -q                 # tests mock HTTP, no network
python examples/smoke_client.py           # live end-to-end over stdio via the MCP client

Works with both mcp 1.x (FastMCP) and 2.x (MCPServer, the renamed FastMCP); CI tests both.

License

MIT

Daily ICHI readings and exploited-vulnerability alerts are posted on X by @ICHI_Global (automated, run by ICHI's creator).