ichi-mcp

Free MCP server for the ICHI Internet Cyber Health Index — returns the current internet-wide threat band (NORMAL to CRITICAL), numeric score, source health, and recent critical vulnerability advisories via three keyless tools. No API key needed.

GitHub

Documentation

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.

Tools

Tool	Source	Returns
`get_current_index`	`GET /api/current-index`	score, rounded score, band + band range, evaluation time, model, per-dimension sub-scores with human-readable names and contributions, informational (unscored) values, freshness/impairment info (headline state, age, stale/impaired/invalid inputs, degraded dimensions), links
`get_recent_alerts(limit=5)`	`GET /api/alerts` (RSS 2.0)	latest N (1–50) items from ICHI's critical-advisory feed: title, link, id, published (ISO-8601), category, description
`get_source_health`	`GET /api/health`	overall status and confidence, feed counts (live/stale/delayed/failed, by tier), sources included in the score, and names of failed/stale/delayed/dormant/not-connected feeds

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

Env var	Default	Meaning
`ICHI_TIMEOUT`	`10`	HTTP timeout in seconds
`ICHI_BASE_URL`	`https://ichi.global`	API base URL (testing only)

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