n3r0-b1n4ry/mcp-abuseipdb
GitHub: n3r0-b1n4ry/mcp-abuseipdb
基于 MCP 协议的 AbuseIPDB 集成服务器，让 AI 助手能够直接查询 IP 滥用信誉并提交举报报告。
Stars: 2 | Forks: 0
# AbuseIPDB MCP Server
一个用于集成 [AbuseIPDB](https://www.abuseipdb.com/) API 的 Model Context Protocol (MCP) 服务器。直接通过您的 AI 助手查询 IP 滥用报告并提交新报告。
[](https://pypi.org/project/mcp-abuseipdb/)
[](https://pypi.org/project/mcp-abuseipdb/)
[](https://modelcontextprotocol.io/)
[](https://hub.docker.com/r/n3r0b1n4ry/abuseipdb-mcp)
[](LICENSE)
[](https://github.com/n3r0-b1n4ry/mcp-abuseipdb)
📦 **安装：** `uvx mcp-abuseipdb` · `pip install mcp-abuseipdb` · [PyPI](https://pypi.org/project/mcp-abuseipdb/)
## 功能
- 🔍 **检查 IP** — 查询 AbuseIPDB 获取任何 IPv4/IPv6 地址的滥用报告及详细信息
- 🚨 **报告 IP** — 为恶意 IP 地址提交滥用报告
- 🚀 **使用 uvx 免安装** — 通过 `uvx mcp-abuseipdb` 即时运行，无需任何设置
- 🌐 **多种传输方式** — Stdio（默认）和 Streamable HTTP（MCP 规范 2025-03-26）
- 📦 **PyPI 包** — 通过 `pip install mcp-abuseipdb` 安装
- 🐳 **Docker 就绪** — 基于 Alpine 的轻量级容器
- ⚡ **Async/Await** — 高性能异步操作
- 🗂️ **完整分类** — 包含易读名称的完整 1-23 类别映射
- 🔄 **速率限制处理** — 针对 429 响应自动重试并提供相关信息
- ✅ **输入验证** — 稳健的 IPv4/IPv6 及参数验证
- 🧹 **清晰的输出** — 为 MCP 客户端优化的可读文本输出
## 快速开始
### 使用 uvx（推荐）
最快的方式 — 无需克隆、无需安装、无需虚拟环境：
```
# 直接运行 (stdio transport)
ABUSEIPDB_API_KEY="your_api_key_here" uvx mcp-abuseipdb
# 使用 HTTP transport
ABUSEIPDB_API_KEY="your_api_key_here" uvx mcp-abuseipdb --transport http --port 8000
```
### 使用 pip
```
pip install mcp-abuseipdb
export ABUSEIPDB_API_KEY="your_api_key_here"
mcp-abuseipdb
```
### 使用 Docker
```
docker build -t abuseipdb-mcp .
docker run -it --rm -e ABUSEIPDB_API_KEY="your_api_key_here" abuseipdb-mcp
```
## 实时演示
### IP 信誉检查与高级分析
*示例：`check_ip` 结合全面的滥用报告、分类、地理位置和威胁情报，分析可疑的 IP 地址。*
*高级用法：结合详细报告、ISP 信息、滥用置信度分数以及近期攻击模式进行详细的 IP 分析。*
## MCP 客户端配置
### Claude Desktop — uvx（推荐）
添加至 `claude_desktop_config.json`：
```
{
"mcpServers": {
"abuseipdb": {
"command": "uvx",
"args": ["mcp-abuseipdb"],
"env": {
"ABUSEIPDB_API_KEY": "your_api_key_here"
}
}
}
}
```
### Claude Desktop — uvx 与 HTTP 传输
```
{
"mcpServers": {
"abuseipdb": {
"command": "uvx",
"args": ["mcp-abuseipdb", "--transport", "http", "--port", "8000"],
"env": {
"ABUSEIPDB_API_KEY": "your_api_key_here"
}
}
}
}
```
### 远程服务器 (Streamable HTTP)
```
{
"mcpServers": {
"abuseipdb": {
"url": "http://your-server:8000/mcp"
}
}
}
```
### Docker (Stdio)
```
{
"mcpServers": {
"abuseipdb": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "ABUSEIPDB_API_KEY=your_api_key_here",
"abuseipdb-mcp"
]
}
}
}
```
### Docker (Streamable HTTP)
```
# 启动 container
docker run -d --rm \
-e ABUSEIPDB_API_KEY="your_api_key_here" \
-e MCP_TRANSPORT=http \
-p 8000:8000 \
abuseipdb-mcp
```
```
{
"mcpServers": {
"abuseipdb": {
"url": "http://localhost:8000/mcp"
}
}
}
```
## 可用工具
### 1. `check_ip`
检查 IP 地址的滥用报告。
| 参数 | 类型 | 必填 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `ipAddress` | string | ✅ | — | 要检查的 IPv4 或 IPv6 地址 |
| `maxAgeInDays` | integer | — | 30 | 仅返回过去 x 天内的报告 (1-365) |
| `verbose` | boolean | — | true | 在响应中包含详细报告 |
**示例输入：**
```
{
"ipAddress": "134.122.87.122",
"maxAgeInDays": 30,
"verbose": true
}
```
**示例输出：**
```
AbuseIPDB Check Results
IP Address: 134.122.87.122
Abuse Confidence Score: 75%
Is Public: Yes
Is Whitelisted: No
Country: United States (US)
ISP: DigitalOcean, LLC
Usage Type: Data Center/Web Hosting/Transit
Domain: digitalocean.com
Total Reports: 15
Categories: Brute-Force, SSH, Port Scan, Hacking
```
### 2. `report_ip`
向 AbuseIPDB 举报滥用 IP 地址。
| 参数 | 类型 | 必填 | 描述 |
|-----------|------|----------|-------------|
| `ip` | string | ✅ | 要举报的 IPv4 或 IPv6 地址 |
| `categories` | string | ✅ | 逗号分隔的类别 ID（例如，`"18,22"`） |
| `comment` | string | — | 攻击的描述文本（不得包含个人身份信息/PII） |
| `timestamp` | string | — | 攻击发生的 ISO 8601 日期时间 |
**示例输入：**
```
{
"ip": "192.168.1.100",
"categories": "18,22",
"comment": "Multiple SSH brute force attempts detected",
"timestamp": "2024-01-15T10:30:00Z"
}
```
### 滥用分类
| ID | 分类 | ID | 分类 | ID | 分类 |
|----|----------|----|---------|----|---------|
| 1 | DNS Compromise | 9 | Open Proxy | 17 | Spoofing |
| 2 | DNS Poisoning | 10 | Web Spam | 18 | Brute-Force |
| 3 | Fraud Orders | 9 | Open Proxy | 17 | Spoofing |
| 2 | DNS Poisoning | 10 | Web Spam | 18 | Brute-Force |
| 3 | Fraud Orders | 11 | Email Spam | 19 | Bad Web Bot |
| 4 | DDoS Attack | 12 | Blog Spam | 20 | Exploited Host |
| 5 | FTP Brute-Force | 13 | VPN IP | 21 | Web App Attack |
| 6 | Ping of Death | 14 | Port Scan | 22 | SSH |
| 7 | Phishing | 15 | Hacking | 23 | IoT Targeted |
| 8 | Fraud VoIP | 16 | SQL Injection | | |
## 传输类型
| 传输方式 | 用例 | 协议 |
|-----------|----------|----------|
| **stdio**（默认） | 本地 MCP 客户端（如 Claude Desktop） | Standard I/O |
| **http** | 远程访问、多客户端、云端部署 | Streamable HTTP（MCP 规范 2025-03-26） |
### 运行服务器
```
# Stdio (默认)
mcp-abuseipdb
# HTTP transport
mcp-abuseipdb --transport http
# 带自定义 host/port 的 HTTP
mcp-abuseipdb --transport http --host 127.0.0.1 --port 3000
# 通过 environment variables
MCP_TRANSPORT=http MCP_PORT=3000 mcp-abuseipdb
```
### 测试 HTTP 传输
```
mcp-abuseipdb --transport http --port 8000
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```
## Docker 部署
### 构建与运行
```
docker build -t abuseipdb-mcp .
docker run -it --rm -e ABUSEIPDB_API_KEY="your_api_key_here" abuseipdb-mcp
```
### Docker Compose
包含的 `docker-compose.yml` 提供了两个预配置的服务：
```
# Stdio service
ABUSEIPDB_API_KEY="your_key" docker compose --profile stdio up abuseipdb-mcp
# HTTP service (暴露于 port 8000)
ABUSEIPDB_API_KEY="your_key" docker compose --profile http up abuseipdb-mcp-http
```
## 开发
### 本地设置
```
git clone https://github.com/n3r0-b1n4ry/mcp-abuseipdb.git
cd mcp-abuseipdb
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
pip install -e .
export ABUSEIPDB_API_KEY="your_api_key_here"
mcp-abuseipdb
```
### 运行测试
```
python -m pytest test/test_server.py -v
```
### 构建与发布
```
python -m build
python -m twine upload dist/*
```
## 错误处理
| 错误 | 行为 |
|-------|----------|
| **速率限制 (429)** | 返回重试等待时间和剩余配额 |
| **无效的 API 密钥** | 清晰的身份验证错误信息 |
| **无效的 IP 格式** | 格式验证及有用的提示信息 |
| **API 错误** | 包含状态码的详细错误响应 |
| **网络问题** | 超时和连接错误处理 |
## 速率限制
| 计划 | 检查端点 | 报告端点 |
|------|---------------|-----------------|
| 免费 | 1,000/天 | 100/天 |
| 基础版 | 3,000/天 | 300/天 |
| 高级版 | 10,000/天 | 1,000/天 |
| 企业版 | 100,000/天 | 10,000/天 |
## 依赖项
| 包 | 版本 | 用途 |
|---------|---------|---------|
| [mcp](https://pypi.org/project/mcp/) | ≥1.12.0, <2.0.0 | Model Context Protocol SDK |
| [httpx](https://pypi.org/project/httpx/) | ≥0.27.0 | 异步 HTTP 客户端 |
| [pydantic](https://pypi.org/project/pydantic/) | ≥2.8.0 | 数据验证 |
| [python-dotenv](https://pypi.org/project/python-dotenv/) | ≥1.0.0 | 环境变量加载 |
| [uvicorn](https://pypi.org/project/uvicorn/) | ≥0.32.0 | ASGI 服务器 (HTTP 传输) |
| [starlette](https://pypi.org/project/starlette/) | ≥0.45.0 | ASGI 框架 (HTTP 传输) |
## 项目结构
```
mcp-abuseipdb/
├── src/
│ ├── abuseipdb_mcp/ # Python package (uvx/pip)
│ │ ├── __init__.py
│ │ ├── server.py # Entry point (package)
│ │ └── modules.py # AbuseIPDBServer class
│ ├── server.py # Entry point (standalone)
│ └── modules.py # AbuseIPDBServer class (standalone)
├── config/
│ ├── mcp.json # MCP server config (stdio)
│ └── mcp-docker.json # MCP Docker config
├── examples/
│ └── mcp-client-configs.json # MCP client config examples
├── images/ # Screenshots and demo images
├── pyproject.toml # Package metadata & build config
├── Dockerfile # Alpine-based container
├── docker-compose.yml # Stdio + HTTP services
├── requirements.txt # Legacy pip dependencies
├── LICENSE # MIT License
└── README.md
```
## 故障排除
| 问题 | 解决方案 |
|---------|----------|
| 出现 `API key required` 错误 | 设置 `ABUSEIPDB_API_KEY` 环境变量 |
| 连接超时 | 检查网络连接和防火墙设置 |
| 超出速率限制 | 等待重试期或升级 AbuseIPDB 套餐 |
| IP 格式无效 | 使用格式正确的 IPv4 或 IPv6 地址 |
| 找不到 `uvx` | 安装 uv：`pip install uv` 或参阅 [uv 文档](https://docs.astral.sh/uv/) |
| MCP 客户端无法连接 | 检查 `claude_desktop_config.json` 的语法和路径 |
## 更新日志
### v1.3.0
- ✅ **uvx / PyPI 支持** — `uvx mcp-abuseipdb` 开箱即用
- ✅ **`pyproject.toml`** — 使用 hatchling 的现代 Python 打包方式
- ✅ **入口点** — 通过 `[project.scripts]` 提供 `mcp-abuseipdb` CLI 命令
- ✅ **Dockerfile 已更新** — 使用 `pip install .` 和入口点
- ✅ **Streamable HTTP 传输** — 符合 MCP 规范 2025-03-26 标准
### v1.2.0
- ✅ 兼容 MCP SDK 1.12.2
- ✅ 直接返回 `TextContent` 列表（替代 `CallToolResult`）
- ✅ 完整的分类映射 (1-23)
- ✅ 默认启用详细模式
- ✅ 清晰的输出格式（无 markdown）
- ✅ Alpine Docker 镜像优化
## 许可证
[MIT 许可证](LICENSE) — 可免费用于个人和商业用途。
**用 ❤️ 为 MCP 社区而制**
标签：AbuseIPDB, AI安全工具, API集成, Docker容器, GitHub, IP信誉查询, IP 地址批量处理, IP黑名单, LLM集成, MCP Server, Prompt Injection, Python, 可观测性, 威胁情报, 密码管理, 开发者工具, 异步编程, 恶意IP检测, 攻击溯源, 攻击面发现, 无后门, 模型上下文协议, 网络安全, 网络攻击报告, 自动化响应, 请求拦截, 运行时操纵, 逆向工具, 隐私保护