IR Toolshed MCP Server

IR Toolshed MCP Server

一款全面的模型上下文协议（MCP）服务，为安全专业人员提供事件响应和网络分析工具。该服务允许 Claude 等 AI Agent 执行各种网络相关查询与分析，协助开展安全调查。

概述

IR Toolshed MCP Server 通过模型上下文协议提供一套网络与安全工具，旨在为网络事件响应人员提供通用服务，使其能够执行以下基础查询：

• ASN（自治系统编号）查询
• DNS 查询与分析
• WHOIS 记录检索
• IP 地理定位
• 以及未来将推出的更多网络分析功能

每种工具都附有作为资源提供的详细文档，方便 AI 系统了解如何使用这些工具以及预期输出。

当前工具

ASN 查询工具

ASN 查询工具会返回有关 IP 地址的信息，包括：

• 查询的 IP 地址
• 与该 IP 地址关联的 AS 编号
• 拥有该 AS 编号的组织名称

DNS 查询工具

DNS 查询工具提供域名的 DNS 记录信息：

• 支持多种记录类型（A、AAAA、MX、NS、TXT）
• 返回格式化的 DNS 记录
• 支持 IPv4 和 IPv6 查询

WHOIS 查询工具

WHOIS 查询工具可检索域名注册信息：

• 域名所有权详情
• 注册日期
• 名称服务器信息
• 注册商详情

地理定位工具

IP 地理定位工具使用 MaxMind 的 GeoLite2 数据库提供位置信息：

• 国家和城市级别的位置数据
• 纬度和经度坐标
• 网络信息
• 时区数据

注意：地理定位工具需要 MaxMind 许可证密钥。你可以：

1. 从以下网址获取免费密钥：https://dev.maxmind.com/geoip/geolite2-free-geolocation-data
2. 任选以下方式：
   • 设置 MAXMIND_LICENSE_KEY 环境变量
   • 使用该工具时将其作为参数提供
   • 在提示时输入密钥

未来版本将添加更多工具。

前提条件

• Python 3.8 或更高版本（推荐 3.13+）
• uv Python 包管理器

安装

1. 克隆此仓库：

git clone <repository-url>
cd ir-toolshed-mcp-server

2. 创建虚拟环境：

uv venv

3. 激活虚拟环境：

Windows 系统：

.venv\Scripts\activate

macOS/Linux 系统：

source .venv/bin/activate

4. 以开发模式安装软件包：

uv pip install -e .

运行服务

使用以下命令启动 MCP 服务：

uv run mcp dev src/mcp_server.py

这将在开发模式下启动服务，使其可供 Claude Desktop 等 MCP 客户端使用。

使用工具

ASN 查询工具

连接到 Claude Desktop 等 MCP 客户端后，可以提供 IP 地址来使用 ASN 查询工具：

asnlookup("8.8.8.8")

输出示例：

{
    "ip_addr": "8.8.8.8",
    "as_number": "15169",
    "as_name": "GOOGLE - Google LLC"
}

DNS 查询工具

连接到 Claude Desktop 等 MCP 客户端后，可以提供域名来使用 DNS 查询工具：

dnslookup("example.com")

输出示例：

{
    "domain": "example.com",
    "record_type": "A",
    "record_value": "93.184.216.34"
}

WHOIS 查询工具

连接到 Claude Desktop 等 MCP 客户端后，可以提供域名来使用 WHOIS 查询工具：

whoislookup("example.com")

输出示例：

{
    "domain": "example.com",
    "ownership_details": "Google LLC",
    "registration_date": "2004-04-26",
    "nameserver_information": "ns1.google.com",
    "registrar_details": "MarkMonitor Inc."
}

地理定位工具

连接到 Claude Desktop 等 MCP 客户端后，可以提供 IP 地址来使用地理定位工具：

geolocation("8.8.8.8")

输出示例：

{
    "ip_addr": "8.8.8.8",
    "country": "US",
    "city": "Mountain View",
    "latitude": 37.40599,
    "longitude": -122.078514,
    "network": "AS15169 Google LLC",
    "timezone": "America/Los_Angeles"
}

错误处理

每种工具都遵循统一的错误处理模式：

通用错误响应格式：

{
    "status": "error",
    "error": "Detailed error message",
    "query": "Original query value"
}

特定工具的错误示例：

ASN 查询：

{
    "ip_addr": "<queried-ip>",
    "status": "error",
    "error": "Invalid IP address format"
}

DNS 查询：

{
    "domain": "<queried-domain>",
    "record_type": "<requested-type>",
    "status": "error",
    "error": "DNS resolution failed"
}

WHOIS 查询：

{
    "domain": "<queried-domain>",
    "status": "error",
    "error": "WHOIS server not available"
}

地理定位：

{
    "ip_addr": "<queried-ip>",
    "status": "error",
    "error": "MaxMind database not found or license key invalid"
}

项目结构

项目遵循标准的 Python 软件包结构：

irtoolshed_mcp_server/     # Main package directory
├── __init__.py           # Package initialization
├── asnlookup.py         # ASN lookup functionality
├── dnslookup.py         # DNS lookup functionality
├── geolookup.py         # Geolocation functionality
├── mcp_server.py        # Main MCP server implementation
└── whoislookup.py       # WHOIS lookup functionality

tests/                    # Test directory
├── test_asnlookup.py    # ASN lookup tests
├── test_dnslookup.py    # DNS lookup tests
├── test_geolookup.py    # Geolocation tests
└── test_whoislookup.py  # WHOIS lookup tests

开发

设置开发环境

1. 克隆此仓库：

git clone <repository-url>
cd ir-toolshed-mcp-server

2. 创建虚拟环境并安装依赖项：

uv venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
uv pip install -e ".[dev]"

运行测试

运行测试套件：

uv run pytest

这将：

• 运行 tests/ 目录中的所有测试
• 显示测试覆盖率信息
• 显示任何失败测试的详细输出

注意：部分测试需要额外配置：

• 地理位置测试需要 MaxMind GeoLite2 数据库和许可证密钥
• 如果 WHOIS 服务不可用，WHOIS 测试可能会失败

代码质量

项目使用多种工具来维护代码质量：

• 使用 Black 格式化代码：

uv run black .

• 使用 isort 对导入排序：

uv run isort .

• 使用 mypy 进行类型检查：

uv run mypy .

• 使用 ruff 运行代码检查：

uv run ruff .

路线图

已完成： ✓ ASN 查询 ✓ DNS 记录查询（A、AAAA、MX 等） ✓ WHOIS 记录检索 ✓ IP 地理位置服务

计划加入的未来工具：

• 域名信誉评分
• SSL 证书分析
• 网络端口扫描
• 威胁情报集成
• 被动 DNS 历史记录
• 电子邮件安全分析（SPF、DKIM、DMARC）
• BGP 路由分析
• 网络流量可视化
• 恶意软件哈希查询
• URL 信誉检查

贡献

欢迎贡献新的 IR 工具或改进现有工具。 请按以下步骤操作：

1. Fork 仓库
2. 创建功能分支
3. 按照 mcp_server.py 中现有的模式添加工具
4. 将相应文档作为资源一并提供
5. 提交 pull request，并清楚描述所做的更改

许可证

Apache 2.0

安全注意事项

本服务旨在用于合法的安全研究和事件响应。 使用这些工具时，用户必须确保遵守所有适用的法律法规。