certindex-mcp

certindex-mcp

一个 MCP（Model Context Protocol）服务，将 CertIndex 的 Certificate Transparency 搜索工具提供给任何兼容 MCP 的客户端（Claude Desktop、MCP Inspector、Continue 等）。

CertIndex 直接从公开的 Certificate Transparency 日志摄取证书，并通过自有索引提供查询服务。历史数据回填仍在进行中，因此结果可能不完整，尤其是较旧的证书。本服务封装了公开的 CertIndex REST API，让大模型可以提出这类问题：

• “列出 CertIndex 为 example.com 索引的 TLS 证书。”
• “Let's Encrypt 发现了 mycompany.io 的哪些子域名？”
• “显示 api.mycompany.io 在未来 30 天内到期的证书。”
• “获取 SHA-256 <fingerprint> 对应的完整 PEM 和 CT 日志元数据。”

为什么会有这个仓库

CertIndex 单体仓库包含一个 MCP 服务（挂载于 https://api.ctindex.io/mcp），可直接连接生产环境的 Postgres 索引。这个独立软件包是一个精简的客户端适配层：它通过 MCP 与你的编辑器 / Agent 通信，并通过 HTTPS 将每次工具调用转发到托管的 CertIndex REST API。由此带来两个好处：

1. 你无需拥有一份索引副本——在 https://ctindex.io 注册一个免费 API 密钥即可。
2. 这个软件包的依赖极少（mcp、httpx、pydantic）——易于审计、易于引入，无需数据库驱动程序。

安装

0.3.0 版使用 MCP Python SDK 2.x（mcp>=2,<3）和 Python 3.11 及更高版本。 控制台命令、环境变量和十个工具名称均未更改。 必须保留 SDK 1.x 的应用程序，请使用 certindex-mcp==0.2.1。

pip install certindex-mcp

也可以使用 uvx 一次性运行：

uvx certindex-mcp

如需改为从源代码安装最新开发版本：

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

快速开始 — Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

重启 Claude Desktop。工具栏中将显示十个 CertIndex 工具。

工具

10 个工具，与托管的 CertIndex MCP 服务一一对应：

工具	功能	重要参数
search_certificates	按域名、CN、颁发者、SAN、有效期或通配符状态搜索 CT 索引。	domain、cn、issuer、san、expired、is_wildcard、page/limit
get_certificate	按 SHA-256 指纹获取单个证书。	sha256、include_enrichment
get_domain_certificates	获取指定精确域名的已索引证书。	valid_only、include_enrichment、include_signals（付费计划）、page/limit
get_subdomains	列出 CT 中出现过的唯一子域名。	偏移量（page/limit）或键集游标模式——传入 cursor="" 开始，然后将每次响应的 next_cursor 传回
get_latest_cert	获取域名当前有效的最新证书。	include_enrichment、include_signals、include_precerts（允许预证书参与“最新”证书的竞争）
get_expiring_certs	获取域名中将在 days 天内到期的证书。	days
submit_global_sweep	提交对整个索引执行的异步、不限域名的 CN/SAN 子串扫描（POST /v1/sweeps）。	cn/san_contains（至少 3 个字符，且至少需要一个）、issuer、is_wildcard、is_precert、expired、first_seen_*/not_after_* 日期范围、strict_attribution、resume_token（在达到结果上限后继续）
get_sweep_results	轮询扫描任务，并在完成后对结果分页（GET /v1/sweeps/{id}）。	sweep_id、page/limit（最多 1,000）
get_usage	调用者的套餐级别、当前用量、剩余额度和权益。	—
get_historical_backfill_status	检查或启动域名的付费深度历史回填。	domain

快速入门 — MCP Inspector

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

配置

环境变量	默认值	说明
CERTINDEX_API_KEY	(必填)	你的 CertIndex API 密钥。前往 https://ctindex.io/app/keys 创建
CERTINDEX_BASE_URL	https://api.ctindex.io	用于覆盖可自托管部署或暂存环境的地址
CERTINDEX_TIMEOUT	30	每次请求的 HTTP 超时时间（秒）

安全

输入验证、速率限制处理和我们的供应链安全状况记录在 SECURITY.md 中。请将漏洞报告发送至 [email protected]，而不要提交公开问题。

开发

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

CI 使用 Python 3.11 / 3.12 / 3.13 和 SDK 2.0.0 及最新允许的 2.x 版本运行。它还会将构建好的 wheel 安装到全新环境中，并通过实际的标准输入/输出测试初始化、工具枚举和调用。 HTTP 测试固件通过回环地址运行；测试无需生产凭据。

许可证

MIT © CertIndex 贡献者。