CertIndex MCP

certindex-mcp

Ein MCP (Model Context Protocol) Server, der die CertIndex Certificate Transparency-Suchwerkzeuge für jeden MCP-kompatiblen Client (Claude Desktop, den MCP Inspector, Continue usw.) bereitstellt.

CertIndex erfasst Zertifikate direkt aus öffentlichen Certificate Transparency-Logs und stellt sie über einen eigenen Index bereit. Der historische Backfill ist noch im Gange, daher können Ergebnisse, insbesondere für ältere Zertifikate, unvollständig sein. Dieser Server kapselt die öffentliche CertIndex-REST-API, sodass ein LLM Fragen stellen kann wie:

• „Liste die TLS-Zertifikate auf, die CertIndex für example.com indexiert hat."
• „Welche Subdomains hat Let's Encrypt für mycompany.io gesehen?"
• „Zeig mir Zertifikate, die in den nächsten 30 Tagen für api.mycompany.io ablaufen."
• „Rufe das vollständige PEM und die CT-Log-Metadaten für SHA-256 <fingerprint> ab."

Warum dieses Repository existiert

Das CertIndex-Monorepo bündelt einen MCP-Server (gemountet unter https://api.ctindex.io/mcp), der direkt mit dem Produktions-Postgres-Index spricht. Dieses eigenständige Paket ist ein schlanker clientseitiger Shim: Es spricht MCP mit Ihrem Editor/Agenten und leitet jeden Werkzeugaufruf über HTTPS an die gehostete CertIndex-REST-API weiter. Zwei Konsequenzen:

1. Sie benötigen keine Kopie des Index – registrieren Sie sich für einen kostenlosen API-Schlüssel unter https://ctindex.io und Sie sind fertig.
2. Das Paket hat einen minimalen Abhängigkeits-Fußabdruck (mcp, httpx, pydantic) – leicht zu prüfen, leicht zu vendoren, keine DB-Treiber.

Installation

Version 0.3.0 verwendet das MCP-Python-SDK 2.x (mcp>=2,<3) und Python 3.11+. Der Konsolenbefehl, die Umgebungsvariablen und die zehn Werkzeugnamen sind unverändert. Für Anwendungen, die SDK 1.x beibehalten müssen, verwenden Sie certindex-mcp==0.2.1.

pip install certindex-mcp

Oder mit uvx für die einmalige Verwendung:

uvx certindex-mcp

Um stattdessen die neueste Entwicklungsversion aus dem Quellcode zu installieren:

pip install git+https://github.com/certindex/certindex-mcp

Schnellstart – Claude Desktop

Fügen Sie zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %APPDATA%\Claude\claude_desktop_config.json (Windows) hinzu:

{
  "mcpServers": {
    "certindex": {
      "command": "uvx",
      "args": ["certindex-mcp"],
      "env": {
        "CERTINDEX_API_KEY": "ctx_live_..."
      }
    }
  }
}

Starten Sie Claude Desktop neu. Die zehn CertIndex-Werkzeuge erscheinen in der Werkzeugleiste.

Werkzeuge

Zehn Werkzeuge, die 1:1 dem gehosteten CertIndex-MCP-Server entsprechen:

Werkzeug	Funktion	Wichtige Parameter
search_certificates	Durchsucht den CT-Index nach Domain, CN, Aussteller, SAN, Gültigkeit oder Wildcard-Status.	domain, cn, issuer, san, expired, is_wildcard, page/limit
get_certificate	Ruft ein einzelnes Zertifikat per SHA-256-Fingerabdruck ab.	sha256, include_enrichment
get_domain_certificates	Indexierte Zertifikate für eine exakte Domain.	valid_only, include_enrichment, include_signals (kostenpflichtige Pläne), page/limit
get_subdomains	Listet eindeutige Subdomains auf, die in CT gesehen wurden.	Offset (page/limit) oder Keyset-Cursor-Modus – übergeben Sie cursor="" zum Start, dann geben Sie die next_cursor jeder Antwort zurück
get_latest_cert	Neuestes aktuell gültiges Zertifikat für eine Domain.	include_enrichment, include_signals, include_precerts (lassen Sie Präzertifikate um „neueste" konkurrieren)
get_expiring_certs	Zertifikate für eine Domain, die innerhalb von days Tagen ablaufen.	days
submit_global_sweep	Startet eine asynchrone, domainlose CN/SAN-Substring-Durchsuchung des gesamten Index (POST /v1/sweeps).	cn/san_contains (3+ Zeichen, mindestens eines erforderlich), issuer, is_wildcard, is_precert, expired, first_seen_*/not_after_* Datumsgrenzen, strict_attribution, resume_token (Fortsetzung über das Ergebnislimit hinaus)
get_sweep_results	Fragt einen Sweep-Job ab und paginiert dessen Ergebnisse, wenn fertig (GET /v1/sweeps/{id}).	sweep_id, page/limit (bis zu 1.000)
get_usage	Tarif des Aufrufers, aktuelle Nutzung, verbleibendes Kontingent und Berechtigungen.	—
get_historical_backfill_status	Prüft/startet den kostenpflichtigen Deep-History-Backfill für eine Domain.	domain

Schnellstart – MCP Inspector

export CERTINDEX_API_KEY=ctx_live_...
npx @modelcontextprotocol/inspector uvx certindex-mcp

Konfiguration

Umgebungsvariable	Standard	Beschreibung
CERTINDEX_API_KEY	(erforderlich)	Ihr CertIndex-API-Schlüssel. Erstellen Sie einen unter https://ctindex.io/app/keys
CERTINDEX_BASE_URL	https://api.ctindex.io	Überschreibung für selbst gehostete Bereitstellungen / Staging
CERTINDEX_TIMEOUT	30	HTTP-Timeout pro Anfrage (Sekunden)

Sicherheit

Eingabevalidierung, Ratenlimit-Behandlung und unsere Supply-Chain-Haltung sind in SECURITY.md dokumentiert. Bitte melden Sie Schwachstellen an security@ctindex.io, anstatt öffentliche Issues zu erstellen.

Entwicklung

git clone https://github.com/certindex/certindex-mcp
cd certindex-mcp
pip install -e ".[dev]"
pytest

CI läuft auf Python 3.11 / 3.12 / 3.13 mit sowohl SDK 2.0.0 als auch der neuesten zulässigen 2.x-Version. Es installiert außerdem das gebaute Wheel in eine frische Umgebung und testet Initialisierung, Werkzeugaufzählung und Aufrufe über echtes stdio. HTTP-Fixtures laufen auf Loopback; Tests erfordern keine Produktions-Anmeldedaten.

Lizenz

MIT © CertIndex-Mitwirkende.