使用说明

Tradecraft MCP

OSINT（开源情报）谍报工具包作为主控程序服务器。提供31个用于领域侦察、电子邮件/身份研究、威胁情报和网络/社交媒体分析的工具，以及12个指导结构化调查工作流程的提示模板。

17个工具无需配置即可开箱即用。剩下的14个使用可选的API密钥解锁，服务器优雅地“告诉”你如何在它们丢失时设置它们。

快速开始

# Install dependencies
uv sync

# Run the server
uv run tradecraft-mcp

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "tradecraft-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/tradecraft-mcp", "tradecraft-mcp"]
    }
  }
}

克劳德代码

claude mcp add tradecraft-mcp -- uv run --directory /path/to/tradecraft-mcp tradecraft-mcp

MCP检查员

uv run mcp dev src/tradecraft_mcp/server.py

远程访问（SSE/流式HTTP）

服务器支持三种传输方式： stdio （默认）， sse，以及 streamable-http。使用基于HTTP的传输在机器上运行服务器并远程连接到它。

# Start with SSE transport on default port 8000
uv run tradecraft-mcp --transport sse

# Start with streamable-http on a custom port
uv run tradecraft-mcp --transport streamable-http --port 9000

# Bind to a specific interface
uv run tradecraft-mcp --transport sse --host 127.0.0.1 --port 8080

然后配置您的MCP客户端以连接到远程URL：

{
  "mcpServers": {
    "tradecraft-mcp": {
      "url": "http://<host>:8000/sse"
    }
  }
}

对于 streamable-http，端点为 http://<host>:<port>/mcp.

跑 uv run tradecraft-mcp --help 查看所有选项。

认证

默认情况下，HTTP传输是打开的。支持三种身份验证模式：静态承载令牌、Google ID令牌验证和完整的Google OAuth流。

静态承载令牌

# Via CLI flag
uv run tradecraft-mcp --transport sse --auth-token my-secret

# Via environment variable
MCP_AUTH_TOKEN=my-secret uv run tradecraft-mcp --transport streamable-http

客户必须包括 Authorization: Bearer my-secret 在每一个请求中。没有有效令牌的请求将收到401响应。

Google ID令牌验证

在不运行完整OAuth流的情况下验证Google颁发的JWT ID令牌。只需要Google OAuth2客户端ID：

# Via CLI flags
uv run tradecraft-mcp --transport sse --google-client-id YOUR_CLIENT_ID

# Restrict to specific emails or domains
uv run tradecraft-mcp --transport sse \
  --google-client-id YOUR_CLIENT_ID \
  --google-allowed-emails alice@example.com,bob@example.com

uv run tradecraft-mcp --transport sse \
  --google-client-id YOUR_CLIENT_ID \
  --google-allowed-domains example.com,mycompany.com

# Via environment variables
MCP_GOOGLE_CLIENT_ID=YOUR_CLIENT_ID uv run tradecraft-mcp --transport sse

完整的Google OAuth流程

对于完整的OAuth2授权代码流（同意屏幕、令牌交换、刷新令牌），请提供客户端ID和客户端密钥：

# Via CLI flags
uv run tradecraft-mcp --transport sse \
  --google-client-id YOUR_CLIENT_ID \
  --google-client-secret YOUR_CLIENT_SECRET

# With email/domain restrictions
uv run tradecraft-mcp --transport sse \
  --google-client-id YOUR_CLIENT_ID \
  --google-client-secret YOUR_CLIENT_SECRET \
  --google-allowed-domains mycompany.com

# Via environment variables
MCP_GOOGLE_CLIENT_ID=YOUR_CLIENT_ID \
MCP_GOOGLE_CLIENT_SECRET=YOUR_CLIENT_SECRET \
  uv run tradecraft-mcp --transport sse

服务器暴露 /oauth/google/callback 作为重定向URI——在您的Google Cloud Console OAuth凭据中配置此URI。

身份验证选项参考

选项	环境变量	描述
`--auth-token`	`MCP_AUTH_TOKEN`	静态承载令牌（设置后启用简单身份验证）
`--google-client-id`	`MCP_GOOGLE_CLIENT_ID`	Google OAuth2客户端ID（启用Google身份验证）
`--google-client-secret`	`MCP_GOOGLE_CLIENT_SECRET`	Google OAuth2客户端密钥（启用完整的OAuth流）
`--google-allowed-emails`	`MCP_GOOGLE_ALLOWED_EMAILS`	允许使用逗号分隔的电子邮件地址
`--google-allowed-domains`	`MCP_GOOGLE_ALLOWED_DOMAINS`	允许使用逗号分隔的电子邮件域
`--issuer-url`	`MCP_AUTH_ISSUER_URL`	OAuth颁发者URL（默认值： `http://localhost:<port>`)
`--required-scopes`	`MCP_AUTH_SCOPES`	逗号分隔的必填范围

CLI标志优先于环境变量。stdio传输忽略Auth。当同时配置了Google身份验证和静态令牌时，Google身份验证优先。

工具

域/IP/DNS重新配置（9个工具）

工具	说明	API密钥
`whois_lookup`	域名或IP的WHOIS——注册商、日期、名称服务器	无
`dns_enumerate`	查询A、AAAA、MX、NS、TXT、CNAME、SOA记录	无
`reverse_dns`	在IP上反向DNS以查找主机名	无
`cert_transparency_search`	在crt.sh中搜索证书和子域	无
`subdomain_discover`	通过CT日志+可选暴力+安全追踪的子域	`SECURITYTRAILS_API_KEY` （可选）
`ip_geolocation`	地理数据--国家、城市、ISP、ASN	无
`shodan_host_lookup`	Shodan主机信息--端口、服务、漏洞、地理位置	`SHODAN_API_KEY`
`shodan_domain_search`	Shodan为域提供主机	`SHODAN_API_KEY`
`censys_host_lookup`	Censys主机——服务、TLS、ASN	`CENSYS_API_ID` + `CENSYS_API_SECRET`

电子邮件和身份（6个工具）

工具	说明	API密钥
`email_validate`	格式检查+MX记录验证	无
`email_domain_info`	MX、SPF、DKIM、DMARC分析+邮件提供商检测	无
`gravatar_lookup`	来自电子邮件哈希的Gravatar配置文件	无
`username_enumerate`	通过HTTP探测跨主要平台检查用户名	无
`hibp_breach_check`	我是否已经进行了漏洞查找	`HIBP_API_KEY`
`hibp_paste_check`	我被粘贴索引查找了吗	`HIBP_API_KEY`

威胁情报（7种工具）

工具	说明	API密钥
`threat_feed_check`	检查Abuse.ch URLhaus、Feodo跟踪器、SSL黑名单	无
`virustotal_file_report`	VirusTotal文件哈希分析	`VIRUSTOTAL_API_KEY`
`virustotal_url_scan`	URL的VirusTotal扫描/报告	`VIRUSTOTAL_API_KEY`
`virustotal_domain_report`	VirusTotal域名信誉+DNS+检测	`VIRUSTOTAL_API_KEY`
`virustotal_ip_report`	VirusTotal IP信誉+相关URL/文件	`VIRUSTOTAL_API_KEY`
`abuseipdb_check`	滥用IPDB报告、信心、ISP	`ABUSEIPDB_API_KEY`
`ioc_enrich`	自动检测IOC类型，查询所有相关工具，合并报表	使用基础键

网络和社交媒体（7个工具）

工具	说明	API密钥
`web_fetch`	以纯文本+元数据的形式获取页面，尊重robots.txt	无
`web_headers_analyze`	安全标头分析——CSP、HSTS、X-Frame、Cookie	无
`metadata_extract`	OpenGraph、推特卡、链接资源、技术指纹	无
`google_dork_generate`	为目标+目标生成Google dork查询	无
`wayback_lookup`	Wayback Machine存档快照	无
`social_media_profile`	从社交媒体URL提取公共配置文件数据	无
`website_technology_detect`	CMS、框架、CDN、分析检测	无

提示模板

提示模板指导结构化调查工作流程。选择一个以获得按正确顺序调用正确工具的分步方法。

领域调查

domain_full_recon --多阶段域重构（WHOIS、DNS、子域、服务、网络、历史）
infrastructure_mapping --从域映射一个组织面向互联网的基础设施
domain_threat_assessment --使用信誉+DNS+证书评估域威胁态势

人员/身份调查

email_investigation --从电子邮件开始：验证、违规、域名、gravatar、用户名搜索
username_investigation --从用户名开始：枚举平台、查找模式、构建配置文件
person_osint --使用所有可用标识符进行全人调查

威胁评估

ioc_investigation --通过富集+威胁信息调查可疑的国际奥委会
malware_hash_analysis --分析恶意软件哈希：VT报告+检测率+行为
suspicious_url_analysis --分析可疑网址：信誉、WHOIS、证书、钓鱼清单
ip_threat_profile --构建IP威胁配置文件：地理+Shodan+滥用IPDB+VT+反向DNS

OSINT将军

osint_methodology --OSINT通用方法框架（计划、收集、处理、分析、报告）
attack_surface_discovery --发现组织攻击面：域、服务、信誉、文档、技术

API密钥

所有钥匙都是可选的。复制 .env.example 到 .env 并填写您所拥有的：

cp .env.example .env

变量	服务	如何获取
`SHODAN_API_KEY`	肖丹	注册（免费版可用）
`CENSYS_API_ID`	人口普查	API页面
`CENSYS_API_SECRET`	人口普查	API页面
`VIRUSTOTAL_API_KEY`	病毒总数	注册（免费版可用）
`HIBP_API_KEY`	我被人欺负了吗	购买密钥
`ABUSEIPDB_API_KEY`	滥用IPDB	注册（免费版可用）
`SECURITYTRAILS_API_KEY`	安全追踪	注册（免费版可用）

当调用需要缺少密钥的工具时，它会返回一条带有设置URL的明确错误消息——没有神秘的失败。

发展

# Install with dev dependencies
uv sync --group dev

# Run tests
uv run pytest tests/ -v

# Run a single test file
uv run pytest tests/test_domain_recon.py -v

项目结构

tradecraft-mcp/
├── pyproject.toml
├── src/
│   └── tradecraft_mcp/
│       ├── __init__.py               # Entry point, version
│       ├── __main__.py               # python -m tradecraft_mcp
│       ├── auth.py                   # Token verification (static + Google)
│       ├── oauth_provider.py         # Google OAuth authorization server provider
│       ├── server.py                 # FastMCP instance, lifespan, registration
│       ├── config.py                 # API key loading from env vars
│       ├── tools/
│       │   ├── __init__.py           # register_all_tools(mcp)
│       │   ├── domain_recon.py       # 9 tools
│       │   ├── email_identity.py     # 6 tools
│       │   ├── threat_intel.py       # 7 tools
│       │   └── web_social.py         # 7 tools
│       └── prompts/
│           ├── __init__.py           # register_all_prompts(mcp)
│           ├── domain_investigation.py
│           ├── person_investigation.py
│           ├── threat_assessment.py
│           └── general_osint.py
└── tests/
    ├── conftest.py
    ├── test_domain_recon.py
    ├── test_email_identity.py
    ├── test_threat_intel.py
    └── test_web_social.py

建筑

身份验证： HTTP传输的可选身份验证——静态承载令牌、Google ID令牌验证或完整的Google OAuth2流（使用MCP SDK TokenVerifier 协议和 OAuthAuthorizationServerProvider)
运输： stdio（默认）、SSE或可流式传输的http——可通过以下方式选择 --transport
HTTP会话： 单身的 aiohttp.ClientSession 通过FastMCP生命周期在所有工具之间共享
输出格式： Markdown字符串针对LLM消费进行了优化
错误处理： 缺少API密钥引发 ValueError （MCP SDK将其视为工具错误）；捕获网络错误并将其作为描述性字符串返回
登录中： 通过Python将所有日志记录到stderr logging --永不标准输出（MCP标准输出传输要求）

许可证

麻省理工学院