vulners-mcp

Vulners MCP 服务

Vulners MCP 是一种模型上下文协议（MCP）服务，可通过 Claude Desktop 等 AI 助手无缝访问 Vulners 漏洞数据库。它让安全研究人员和开发者能够通过自然语言对话直接查询全面的漏洞数据、搜索 CVE、分析安全公告并审计软件包。

功能

• AI 助手集成：原生支持 Claude Desktop 和其他兼容 MCP 的客户端
• 双传输协议支持：自动检测并支持 stdio（用于 Claude Desktop）和 HTTP 传输协议
• 丰富的工具：提供 7 种用于漏洞研究的 MCP 工具，包括：
  • 在 400 多万个漏洞公告中进行 Lucene 全文搜索
  • 检索 CVE 和公告信息
  • 审计软件／软件包漏洞
  • 搜索 CPE 并自动补全
  • 审计 Linux 软件包漏洞
• 灵活部署：可使用预构建的 Docker 镜像（ghcr.io/vulnerscom/vulners-mcp）、PyPI 软件包或本地构建
• 基于环境变量的配置：通过环境变量即可轻松设置

目录

• 要求
• 获取 Vulners API 密钥
• 身份验证
• 托管服务：mcp.vulners.com
• 使用 Claude Desktop 快速开始
• 安装与部署
  • PyPI
  • 使用运行脚本的 Docker
  • Docker（手动）
  • 本地构建并运行
• 配置／环境变量
• 用法与端点
• 测试
• 可用工具
• 开发与贡献
• 许可证

---

要求

• Python 3.13+（用于 PyPI 或本地构建）
• 可访问 Vulners API（有效的 API 密钥和网络连接）
• （使用 Docker 时）Docker 引擎

---

获取 Vulners API 密钥

请在 Vulners 网站注册。 点击右上角的姓名，打开个人菜单。 进入“API KEYS”选项卡。 生成作用域为“api”的 API 密钥，并在库中使用。

---

身份验证

API 密钥的提供方式取决于所使用的传输协议：

传输协议	运行方	密钥提供方式
stdio	你，在本地运行（Claude Desktop、本地构建）	VULNERS_API_KEY 环境变量，在本地服务进程中设置一次。这是你自己的密钥，仅供你自己的本地服务实例使用。
HTTP（mcp.vulners.com 或你自己的托管部署）	共享／公共服务，可能为许多调用方提供服务	可在每个请求中发送你自己的 X-Api-Key HTTP 标头（享有完整限额，原样转发），也可以不提供密钥——请参阅下方的匿名层级。

匿名层级（仅限 HTTP）

initialize 和 tools/list 始终无需密钥即可正常工作，因此 Agent 可以先了解服务提供的功能，再决定是否获取密钥。不带 X-Api-Key 请求头发送的 tools/call，其行为取决于此部署是否配置了匿名层级：

调用方	tools/call 行为
没有 X-Api-Key，已配置匿名层级	允许。 使用此部署的匿名层级密钥转发请求。任何 size 类参数都会被限制在较小的上限内，匿名调用还会共享适度的应用级速率限制。如果该上游密钥触及自身的配额或速率限制，你会收到结构化错误，提示你发送自己的密钥。
没有 X-Api-Key，未配置匿名层级	立即失败并返回结构化的引导错误（见下文）——不会向上游发送任何内容。
存在 X-Api-Key，但 Vulners 拒绝该密钥（401/403）	返回经过净化的错误。服务绝不会在你不知情的情况下改用匿名层级密钥。
存在 X-Api-Key 且有效	原样转发，享有完整限制，不进行参数限制，也没有应用级速率限制。

引导错误示例（没有密钥，且未配置匿名层级）：

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "This server does not hold a privileged API key, and no anonymous tier is configured on this deployment. Send your personal Vulners API key in the X-Api-Key HTTP header. Get a key: sign in at https://vulners.com/userinfo (human, in a browser). Details: https://mcp.vulners.com/auth.md (When configured, this server's anonymous tier is itself size- and rate-limited -- your own key always gets full limits.)"
  }]
}

发送自己的 X-Api-Key 始终可在此层获得完整且不受限制的访问权限。匿名层级的存在，是为了让 Agent 可以试用此服务，或偶尔进行轻量调用，而无需先获取密钥。

对于已经设置 VULNERS_API_KEY 的部署，无需更改环境变量即可启用匿名层级。 在 HTTP 模式下，如果未设置 VULNERS_MCP_ANON_API_KEY，它会回退到 VULNERS_API_KEY——因此，同一个密钥现在也会用于匿名层级（该层级有速率限制，且会限制参数大小）。如果要使用单独的专用密钥作为匿名层级密钥——这样它就不会同时成为你自己的运维密钥——请显式设置 VULNERS_MCP_ANON_API_KEY；如果两者都已设置，它始终优先于 VULNERS_API_KEY 的回退值。

---

托管服务：mcp.vulners.com

无需安装：将任何支持 Streamable HTTP 的 MCP 客户端指向

https://mcp.vulners.com/mcp

并在 X-Api-Key 请求头中发送你的 Vulners API 密钥（请参阅获取 Vulners API 密钥）。例如：

# Claude Code
claude mcp add --transport http vulners https://mcp.vulners.com/mcp \
  --header "X-Api-Key: YOUR_API_KEY"

Cursor 配置位于 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "vulners": {
      "url": "https://mcp.vulners.com/mcp",
      "headers": { "X-Api-Key": "YOUR_API_KEY" }
    }
  }
}

其他客户端的相同配置片段可在连接指南中找到：https://mcp.vulners.com/。

---

使用 Claude Desktop 快速入门

使用 Vulners MCP 最简单的方式是通过 Claude Desktop：

1. 拉取 Docker 镜像

docker pull ghcr.io/vulnerscom/vulners-mcp:latest

镜像适用于 linux/amd64 和 linux/arm64，标签包括 latest 以及各个发布版本（例如 1.15.0）。如需自行构建，请参阅从源代码构建。

2. 配置 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vulners": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VULNERS_API_KEY=YOUR_API_KEY_HERE",
        "ghcr.io/vulnerscom/vulners-mcp:latest"
      ]
    }
  }
}

将 YOUR_API_KEY_HERE 替换为你实际的 Vulners API 密钥。

3. 重启 Claude Desktop

保存配置后，重启 Claude Desktop。点击 🔌 图标即可使用 Vulners MCP 服务。

4. 开始使用

现在你可以向 Claude 提出这类问题：

• “查找 Google Chrome 中最近的漏洞”
• “显示 CVE-2025-53770 的详细信息”
• “Citrix 产品中最近有哪些已被利用的漏洞？”
• “审计此软件：cpe:2.3:a:google:chrome:138.0.7204.184:::::::*”
• “审计 ubuntu 22.04 软件包 'openssl 3.0.2 amd64' 和 'curl 7.81.0-1ubuntu1.14 amd64'”

---

安装与部署

PyPI

# stdio (Claude Desktop and other local MCP clients)
VULNERS_API_KEY="your_api_key" uvx vulners-mcp

# or install it
pip install vulners-mcp
VULNERS_API_KEY="your_api_key" vulners-mcp

对于 Claude Desktop，请在 "env" 中设置 VULNERS_API_KEY，并使用 "command": "uvx", "args": ["vulners-mcp"]。

使用运行脚本启动 Docker

如需轻松部署 HTTP 模式，请使用提供的运行脚本：

./run-docker.sh

该脚本会运行本地构建的 vulners-mcp:latest 镜像（参见 从源代码构建）。服务器将以 HTTP 模式在 http://0.0.0.0:8000/mcp 启动。启动时无需 API 密钥——请参见身份验证：每个调用方在每次请求中通过 X-Api-Key 标头发送自己的密钥。

Docker（手动）

以 HTTP 模式运行 MCP 服务（启动时无需 API 密钥）：

docker run -d \
  --name vulners-mcp-http \
  -e MCP_TRANSPORT_MODE="http" \
  -e VULNERS_BASE_URL="https://vulners.com" \
  -p 8000:8000 \
  ghcr.io/vulnerscom/vulners-mcp:latest

调用方随后在每次请求中发送自己的密钥，例如：

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Api-Key: your_api_key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_supported_os","arguments":{}}}'

对于 Claude Desktop（stdio 模式），则使用 -i 标志，并将密钥设置为环境变量（参见身份验证——stdio 没有可用于传递密钥的逐请求标头）：

docker run -i --rm \
  -e VULNERS_API_KEY="your_api_key" \
  ghcr.io/vulnerscom/vulners-mcp:latest

在本地构建并运行

git clone https://github.com/vulnersCom/vulners-mcp.git
cd vulners-mcp
poetry install
# Default transport is stdio, which is why a key belongs in the environment
# here -- see Authentication above. Not needed/used if you instead run with
# MCP_TRANSPORT_MODE=http.
export VULNERS_API_KEY="your_api_key"
poetry run python -m vulners_mcp

---

配置／环境变量

变量	类型	默认值	说明
VULNERS_API_KEY	字符串	未设置	**stdio 传输：**本地运维人员自己的 Vulners API 密钥（参见身份验证）。**HTTP 传输：**当未设置 VULNERS_MCP_ANON_API_KEY 时，也会为匿名层提供密钥——如果部署环境已设置此变量，则无需更改环境即可启用匿名层。
VULNERS_MCP_ANON_API_KEY	字符串	未设置	**仅限 HTTP 传输。**为匿名层提供密钥的 Vulners API 密钥——未发送 X-Api-Key 的调用方将使用此密钥转发请求，而不会被拒绝（参见匿名层（仅限 HTTP））。设置后优先于 VULNERS_API_KEY 回退值。如果两者都未设置，则不存在匿名层：无密钥的 tools/call 会收到引导错误。
ANON_MAX_SIZE	整数	10	HTTP 模式，仅限匿名层。匿名层调用中，任何顶层整数类型的 size 工具参数都会被限制为此值。有密钥的调用不会受到限制。
VULNERS_BASE_URL	字符串	https://vulners.com	Vulners API 的基础 URL（不含 /api 后缀）
MCP_TRANSPORT_MODE	字符串	stdio	强制指定传输模式：http 或 streamable-http
MCP_STATELESS_HTTP	布尔值	true	仅限 HTTP 模式。每个请求都会使用独立传输，不保持服务端 mcp-session-id 连续性，因此服务器可在负载均衡器后水平扩展，无需粘性路由。
MCP_RATE_LIMIT_RPS	数字	30	HTTP 模式，仅限匿名层。宽松的全局（而非按调用方划分）每秒请求数上限，用于保护共享匿名层密钥的配额——作为最后手段的防滥用措施。有密钥的调用不会受此限制；实际的按 IP 限流应在托管部署前的边缘层（例如 Cloudflare）实施。
FASTMCP_HOST	字符串	0.0.0.0	MCP 服务绑定的主机／接口（仅限 HTTP 模式）
FASTMCP_PORT	整数	8000	MCP 服务的端口（仅限 HTTP 模式）
FASTMCP_STREAMABLE_HTTP_PATH	字符串	/mcp	streamable MCP 端点的路径（仅限 HTTP 模式）

指标（默认关闭）。Docker 镜像内置了两种后端；通过 PyPI 安装时，请添加额外依赖：pip install "vulners-mcp[metrics]"（或 [prometheus]／[statsd]）。

变量	类型	默认值	描述
MCP_METRICS_ENABLED	boolean	false	全局开关。只有当此项为 true 且 MCP_METRICS_MODE 不为 none 时，才会收集指标。
MCP_METRICS_MODE	string	none	prometheus、statsd、both 或 none。
MCP_METRICS_PREFIX	string	mcp	每个指标名称的前缀（mcp_tool_calls_total 等）。
MCP_METRICS_PROM_HOST	string	127.0.0.1	Prometheus /metrics 端点的绑定地址。在容器中设置为 0.0.0.0。
MCP_METRICS_PROM_PORT	integer	9100	Prometheus /metrics 端点的端口。
MCP_METRICS_STATSD_HOST	string	127.0.0.1	StatsD 主机。
MCP_METRICS_STATSD_PORT	integer	8125	StatsD UDP 端口。
MCP_METRICS_STATSD_SAMPLE_RATE	number	1.0	StatsD 采样率，范围为 0.0–1.0。

传输模式：

• 服务会根据运行方式自动检测传输模式
• 使用 MCP_TRANSPORT_MODE=http 可显式强制启用 HTTP 模式（用于独立 HTTP 服务）
• 使用 docker run -i 运行时，Claude Desktop 会自动使用 stdio 模式

---

用法与端点

使用 Claude Desktop

只需用自然语言提问：

• “搜索 Apache 漏洞”
• “获取 CVE-2024-1234 的信息”
• “审计软件 cpe:/a:vendor:product:version”

HTTP 模式

在 HTTP 模式下运行时，客户端连接到：

http://<FASTMCP_HOST>:<FASTMCP_PORT>/mcp

默认值：http://0.0.0.0:8000/mcp

每次请求都通过 X-Api-Key 标头发送 Vulners API 密钥，以获得不受限制的完整配额（参见身份验证）。initialize 和 tools/list 始终无需密钥即可使用；不带密钥的 tools/call 要么使用此部署配置的匿名层级（配额较低），要么立即返回包含指导信息的结构化错误，而不会转发到上游服务（如果未配置匿名层级）。

该服务是无状态的（默认设置为 MCP_STATELESS_HTTP=true）：每个请求都会独立处理，各次调用之间无需保持服务端会话连续性，因此可部署在负载均衡器后，无需启用粘性路由。

---

测试

poetry install --with dev
poetry run ruff check .
poetry run pytest

测试套件会模拟 Vulners API，因此无需密钥或网络访问。

---

可用工具

该服务提供 7 个用于漏洞研究的 MCP 工具：

搜索与发现

• search_lucene - 🔍 用于发现未知漏洞的工具 🔍 使用 Lucene 语法在 Vulners 知识库中进行全文搜索。仅在没有具体 ID 或版本信息时使用。绝不要用于已知的 CVE/公告 ID——请改用 bulletin_by_id。绝不要用于具体软件版本（例如“Chrome 138.0.7204.184”）——请改用 audit_software。🚨 重要：搜索供应商/产品时，始终使用 cnaAffected.vendor 和 cnaAffected.product 字段——affectedSoftware 字段不存在。

• bulletin_by_id - 🚨 用于已知 ID 的主要工具 🚨 按 CVE 或 Vulners ID 获取公告。默认返回紧凑的分诊卡片摘要——包括 id、title、CVSS3、EPSS、CVE 列表以及简要的利用/AI 信号，而非完整记录。传入 fields=[...] 可扩展返回内容（例如添加 'description'、'cvss'、'cvss2'、'affectedSoftware'），也可设置 references=True 获取关联公告图；请求所有内容可能会产生非常大的结果。支持单个 ID 或 ID 列表。提供列表时，references 会自动设为 False。绝不要使用 search_lucene 查询已知 ID。

• query_autocomplete - 用于搜索输入的自动补全辅助工具（供应商、产品、CVE 等）。从 Vulners 数据库获取搜索建议。

• search_cpe - 按供应商和产品查找 CPE 字符串（最新架构）。在 Vulners 数据库中搜索通用平台枚举标识符。

漏洞审计

• audit_software - 🔍 特定版本软件审计 🔍 审计特定软件版本是否存在已知漏洞。已知确切的软件版本信息时使用（例如，Chrome 138.0.7204.184）。切勿使用 search_lucene 进行特定版本的软件审计。

• audit_linux_packages - 针对给定发行版和版本审计 Linux 软件包（RPM/DEB）。根据 Vulners 数据库分析 Linux 软件包漏洞。

信息与系统支持

• get_supported_os - 列出 Linux 软件包审计支持的操作系统标识符和版本。获取可用于漏洞分析的操作系统列表。

工具选择指南

🚨 关键工具选择规则 🚨

何时使用各个工具

• bulletin_by_id：已知具体 ID 时使用

  • ✅ “分析 CVE-2025-7775” → bulletin_by_id
  • ✅ “查询 CTX694938” → bulletin_by_id
  • ✅ “介绍一下 CVE-2021-44228” → bulletin_by_id
  • ✅ 任何具体的 CVE、RHSA、MS、CTX、NCSC、THN 等 ID

• search_lucene：仅在没有具体 ID、需要发现漏洞时使用

  • ✅ “查找 Apache 中的漏洞” → search_lucene
  • ✅ “显示近期 CVE” → search_lucene
  • ✅ “Chrome 存在哪些漏洞？” → search_lucene
  • ❌ 已知 ID 时切勿使用——应改用 bulletin_by_id

• audit_software：用于特定版本的软件审计

  • ✅ “审计 Chrome 138.0.7204.184” → audit_software
  • ✅ “检查 Firefox 120.0 中的漏洞” → audit_software
  • ✅ 已知供应商、产品和版本信息时使用
  • ❌ 只有供应商和产品信息时不要使用（应改用 search_lucene）

效率规则：已知 ID 时，调用一次 bulletin_by_id 即可。除非明确要求扩大范围，否则不要再调用 search_lucene。

审计工具的后续工作流

使用审计工具时（audit_software、audit_linux_packages）

• ✅ 运行审计工具，识别易受攻击的软件并获取 CVE ID
• ✅ 从响应的 vulnerabilities 数组中提取 CVE ID
• ✅ 使用包含 CVE ID 的列表调用 bulletin_by_id，进行详细分析
• ✅ 这样可以获取全面的漏洞信息，包括补丁、参考资料和利用数据
• ✅ 使用 bulletin_by_id 批量处理，比多次单独调用更高效

如需查看详细的工具文档和参数，请使用 Claude 的工具检查功能，或查看服务端的工具列表。

---

开发与贡献

• 在 GitHub 上提交问题或功能请求
• 提交改进内容的拉取请求
• 确保与 Vulners API 兼容
• 测试 stdio（Claude Desktop）和 HTTP 模式

从源代码构建

git clone https://github.com/vulnersCom/vulners-mcp.git
cd vulners-mcp
docker build -t vulners-mcp:latest .

发布

每次推送到 main 都会构建 Docker 镜像并发布到 GHCR（latest 和 <version> 标签）。当 pyproject.toml 中的 version 有更新时，同一 工作流还会将软件包发布到 PyPI，并将 server.json 发布到 MCP Registry。每次更改时，都要更新 pyproject.toml 中的版本以及 server.json 中的两个位置（tests/test_server_json.py 会检查它们 是否一致）。

---

许可证

MIT

---

MCP 名称：io.github.vulnersCom/vulners-mcp