WhiteIntel-MCP

将 WhiteIntel 的凭证泄露、暗网情报、品牌保护和支付欺诈能力接入 MCP 客户端

支持能力

快速开始

使用 uvx（推荐）

要求 Python >=3.10。将以下配置加入支持 MCP 的客户端即可，无需预先安装：

{
  "mcpServers": {
    "whiteintel": {
      "command": "uvx",
      "args": [
        "whiteintel-mcp"
      ],
      "env": {
        "WHITEINTEL_API_KEY": "your_whiteintel_api_key"
      }
    }
  }
}

使用 pip

也可以从 PyPI 安装后运行：

python -m pip install -U whiteintel-mcp
whiteintel-mcp

此时将客户端配置中的 command 改为 whiteintel-mcp，并将 args 设为 []。

从源码运行

git clone https://github.com/helGayhub233/WhiteIntel-MCP.git
cd WhiteIntel-MCP
uv sync
uv run whiteintel-mcp

HTTP 部署

本地客户端通常使用默认的 stdio 传输。需要向其他进程提供服务时，可以启动 Streamable HTTP endpoint：

WHITEINTEL_API_KEY=YOUR_KEY whiteintel-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --streamable-http-path /mcp

HTTP/SSE 默认只允许绑定 loopback 地址。对外监听前必须通过前置代理或嵌入式 MCP Host 完成认证；WHITEINTEL_MCP_ALLOW_INSECURE_REMOTE=true 仅用于已有可信 认证代理的场景。嵌入部署时，create_server() 支持 MCP SDK 的 AuthSettings 和 TokenVerifier。

SDK 2.0.0 已移除 mount_path。需要挂载到现有 ASGI 应用时，请使用 streamable_http_app() 并由宿主应用管理 lifespan。

环境变量

API Key 可从 WhiteIntel 获取。完整配置示例见 mcp.json.example 和 .env.example。

工具列表

默认仅暴露只读工具。设置 WHITEINTEL_ENABLE_WRITE_TOOLS=true 后才会注册 Watchlist 和 Supplier 写工具；HTTP 部署仍需按调用者身份和 scope 授权。

工具直接返回 WhiteIntel 的结构化结果。失败响应会转换为 MCP Tool Execution Error （wire JSON 中为 isError: true，Python SDK 字段为 is_error=True），并保留上游消息、HTTP 状态和限流信息。稳定错误码包括 AUTH_INVALID、ENTITLEMENT_REQUIRED、QUOTA_EXHAUSTED、RATE_LIMITED、 INVALID_REQUEST、FORBIDDEN、UPSTREAM_UNAVAILABLE 和 UPSTREAM_ERROR。

按套餐限制工具范围

项目不会通过逐接口试探来猜测账号权限。部署者可以按套餐显式限制可用模块：

WHITEINTEL_ENABLED_MODULES=credential_exposure,entity_lookup,analytics \
  whiteintel-mcp

支持的模块为：credential_exposure、entity_lookup、threat_feed、analytics、 brand_protection、watchlist、supplier_security、audit、payment_fraud。

文档资源

docs/*.md 会以 whiteintel://docs/{filename} 形式暴露为 MCP Resource。客户端可以按需 读取接口说明，例如：

• whiteintel://docs/consumer-leaks-api.md
• whiteintel://docs/threat-feed-api.md
• whiteintel://docs/watchlists-api.md
• whiteintel://docs/card-check-api.md

请求限制

项目在请求上游前执行参数校验和进程内节流；API Key 权限、套餐、额度和风控结果以 WhiteIntel 返回为准。

频率控制仅在单个 MCP 进程内生效，多进程之间不共享状态。

项目结构

src/
  whiteintel_mcp/
    server.py                    # MCPServer 入口、工具注册、resources 注册
    cli.py                       # CLI 兼容入口
    tool_errors.py               # 上游错误分类和 MCP ToolError 转换
    tool_policy.py               # 模块 allowlist 和写工具暴露策略
    models/
      common.py                  # 共享 Pydantic mixin 和字段校验
      endpoints.py               # 各 WhiteIntel endpoint 请求模型
      responses.py               # 稳定的 MCP 输出包装
    services/
      whiteintel_client.py       # 上游 HTTP client 和 429 延迟重试处理
      upstream_rate_limiter.py   # 进程内请求节流

发布验证

PYTHONPYCACHEPREFIX=/tmp/whiteintel-pyc python -m compileall src/whiteintel_mcp
uv build --wheel

项目同时兼容 MCP 2026-07-28 和 2025-11-25；版本记录见 CHANGELOG.md。

合规使用

请仅在合法授权范围内查询和处理威胁情报数据，并遵守 WhiteIntel 的 API 服务条款、 订阅权限和额度限制。

使用者应自行确保其数据处理行为符合适用法律和组织政策。

许可证

MIT License，见 LICENSE。