Web Check MCP

Agent wrapper for Lissy93/web-check — 31 OSINT checks as MCP tools + CLI.

Gap verified 2026-07-25: no public MCP/SDK/Hermes skill existed for this API. This package fills it.

Features

• 8 MCP tools: webcheck_run, webcheck_ssl, webcheck_dns, webcheck_security, webcheck_headers, webcheck_whois, webcheck_list_checks, webcheck_health

• 31 OpenAPI checks from upstream (ssl, dns, headers, ports, firewall, whois, …)

• Presets: quick | security | server | quality | heavy | all

• Parallel fan-out + payload truncation (agent-context safe)

• Zero pip deps — Python 3.10+ stdlib only

• STDIO JSON-RPC with initialize handshake + tool annotations (readOnlyHint + openWorldHint)

Related MCP server: OSINT Tools MCP Server

Public API works (with fallback)

Two public bases are tried automatically:

Set WEB_CHECK_BASE_URL explicitly to skip probing. Fallback auto-enables when base starts with https://web-check. and can be forced via WebCheckClient(fallback=True).

No key, no auth.

Self-host (optional)

For heavy load or offline use:

docker run -d --name web-check -p 3000:3000 lissy93/web-check
export WEB_CHECK_BASE_URL=http://127.0.0.1:3000/api

Or compose (upstream + thin MCP image):

docker compose up -d web-check
# MCP stdio still launched by host; see Dockerfile ENTRYPOINT

Upstream Go rewrite xray-web/web-check-api is early WIP — prefer Node/Docker image for full endpoint parity.

Quick Start

# from repo root
pip install -e .
# or: python3 -m pip install web-check-mcp

# Manifest
python3 -m src.server --manifest

# List checks
python3 -m src.server list --group quick

# Health probe
python3 -m src.server health

# Run quick recon (needs live API)
python3 -m src.server run example.com --group quick

# Single check
python3 -m src.server check ssl example.com

# MCP STDIO (Claude Desktop / Hermes / Cursor)
python3 -m src.server --stdio

Library

from src.client import WebCheckClient

client = WebCheckClient(base_url="http://127.0.0.1:3000/api")
print(client.run("example.com", group="quick"))
print(client.check_one("ssl", "example.com"))

MCP client config

{
  "mcpServers": {
    "web-check": {
      "command": "python3",
      "args": ["-m", "src.server", "--stdio"],
      "cwd": "/absolute/path/to/web-check-mcp",
      "env": {
        "WEB_CHECK_BASE_URL": "http://127.0.0.1:3000/api"
      }
    }
  }
}

After pip install web-check-mcp:

{
  "mcpServers": {
    "web-check": {
      "command": "web-check-mcp",
      "args": ["--stdio"],
      "env": {
        "WEB_CHECK_BASE_URL": "https://web-check.as93.net/api"
      }
    }
  }
}

Official registry metadata lives in server.json (io.github.AMEOBIUS-space/web-check-mcp). Publish with mcp-publisher after the next PyPI release that includes the mcp-name marker above.

Tool Reference

Env: WEB_CHECK_BASE_URL, WEB_CHECK_TIMEOUT, WEB_CHECK_MAX_WORKERS, WEB_CHECK_MAX_CHARS.

Tests

python3 -m pytest tests/ -v

All network paths mocked — no live API required for CI.

Production Readiness Features (unreleased; target v0.4.0)

These features are available on main. The latest published package remains v0.3.0; the v0.4.0 release and MCP Registry namespace migration are tracked in #45.

Reliability

Retry Logic - Auto-retries transient failures (5xx, connection errors) with exponential backoff (1s, 2s, 4s). Configure: WEB_CHECK_MAX_RETRIES (default: 3)

Circuit Breaker - Protects failing APIs. Per base_url tracking, opens after 5 failures, auto-recovers after 60s, fails fast when open.

Input Validation - Validates URLs, check names, groups, timeouts. Clear error messages instead of exceptions.

Performance

Caching - TTL-based cache reduces redundant API calls. Configure: WEB_CHECK_CACHE_TTL (default: 300s). Stats in health endpoint.

Rate Limiting - Token bucket protects API. Configure: WEB_CHECK_RATE_LIMIT (default: 1.0 req/s). Burst: 10 requests.

Environment Variables

Production Deployment

1. Self-host Web Check API: docker run -p 3000:3000 lissy93/web-check

2. Set WEB_CHECK_BASE_URL: Point to your instance

3. Enable caching: Configure WEB_CHECK_CACHE_TTL

4. Configure rate limiting: Adjust WEB_CHECK_RATE_LIMIT

5. Monitor health endpoint: Use cache/rate stats

6. Use Docker: Non-root user, healthcheck included

License

MIT. Upstream Web Check © Alicia Sykes, MIT.

Not affiliated with Lissy93; thin agent-facing client only.