WhiteIntel-MCP

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

支持能力

快速开始

1. 安装 uv

uvx（uv 自带）是 Python 生态中 npx 的等价物——在临时隔离环境中下载并运行包，无需全局安装。

# Linux / macOS（官方安装脚本）
curl -LsSf https://astral.sh/uv/install.sh | sh

# macOS（Homebrew）
brew install uv

2. 配置 MCP 客户端

将以下配置加入支持 MCP 的客户端（Claude Desktop、Cursor 等），无需预先安装 WhiteIntel-MCP：

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

版本锁定（生产环境推荐）：将 args 替换为 ["--from", "whiteintel-mcp==0.5.0", "whiteintel-mcp"]，避免随发布版本浮动。

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

其他安装方式

pip：

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

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

pipx：

pipx install whiteintel-mcp
whiteintel-mcp

从源码：

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

配置

环境变量

启用写工具

写工具（watchlist 和 supplier 的增删改操作）默认不暴露，防止意外修改远程资源。

WHITEINTEL_ENABLE_WRITE_TOOLS=true whiteintel-mcp

或在客户端配置中设置：

"env": {
  "WHITEINTEL_API_KEY": "your_key",
  "WHITEINTEL_ENABLE_WRITE_TOOLS": "true"
}

启用后注册的 7 个写工具：

HTTP/SSE 部署启用写工具后，仍需通过 MCP OAuth 或认证代理按调用者身份授权。

按套餐限制工具范围

部署者可按套餐显式限制可用模块，无需逐接口试探权限：

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。

工具列表

默认暴露 16 个只读工具；启用写工具后额外注册 7 个写工具（见启用写工具）。

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

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 进程内生效，多进程之间不共享状态。

文档资源

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

项目结构

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   # 进程内请求节流

开发

# 编译检查
python -m compileall src/whiteintel_mcp

# 运行测试
uv run python -m unittest discover -s tests -v

# 构建 wheel
uv build --wheel

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

合规使用

请仅在合法授权范围内查询和处理威胁情报数据，并遵守 WhiteIntel 的 API 服务条款、订阅权限和额度限制。使用者应自行确保其数据处理行为符合适用法律和组织政策。

许可证

MIT License，见 LICENSE。