nist-nvd-mcp-server

---

概览

来自 NIST 国家漏洞数据库的 CVE 和 CPE 数据。按关键词、严重性、CWE 或 CISA KEV 状态搜索并审计漏洞，将产品解析为 CPE 名称，并追踪 CVE 的修订历史。

工具

工具	描述
nvd_search_cves	按关键词、严重性、CWE、日期范围或 CISA KEV 状态搜索 CVE。
nvd_get_cve	按 ID 获取一个或多个 CVE——包括完整的 CVSS 评分、CWE、CPE 配置、KEV 字段和引用。
nvd_search_cpes	按产品关键词或部分匹配字符串搜索 NVD CPE 字典。
nvd_audit_cpe	按 CPE 名称或虚拟匹配字符串，查找影响特定产品版本的所有 CVE。
nvd_get_cve_history	获取 CVE 的变更历史——包括评分修订、状态变更和引用新增记录。

资源

资源	描述
nvd://cve/{cveId}	按 ID 获取完整 CVE 记录——单个 ID 的数据与 nvd_get_cve 相同，并提供稳定 URI 以便注入上下文。
skill://nist-nvd-guide/SKILL.md	产品适用性、标识符链、严重性解读和覆盖范围指南。

也可以通过 nvd_get_cve 获取 CVE 资源数据。已发布的指南也可供插件安装使用，路径为 skills/nist-nvd-guide/SKILL.md。

能力参考

超出读取上限的请求默认会被限制：CVE 搜索、审计和历史记录为 2000；CPE 搜索为 10000；批量查询为 100 个 ID。被限制的调用会在两个输出面中报告 requestedLimit、effectiveLimit 和提示信息。批量查询会校验每个提供的 ID，并将处理前缀之外经规范化、去重的 ID 列在 unprocessedIds 中；missingIds 仅涵盖已查询的 ID。在启动前设置 NVD_CLAMP_LIMITS=false，即可恢复公布的最大值，并拒绝超出上限的请求。零、负数和小数形式的限制仍然无效。

nvd_search_cves _工具

• 全文关键词搜索（单词之间采用 AND 语义），或设置 exactPhrase: true 进行精确短语匹配——必须提供 keyword
• 筛选条件：CVSS 严重性等级（LOW/MEDIUM/HIGH/CRITICAL——CRITICAL 需要 severityVersion: "v3" 或 "v4"）、CWE ID、CISA KEV 状态、noRejected（默认为 true）
• 日期筛选：pubDays/lastModDays 便捷简写（自动限制为 120 天，限制情况会在补充信息中报告），或显式指定 ISO 8601 范围（跨度最多 120 天，必须提供起止日期）；同一轴上的两种形式不能同时使用
• 使用 limit（最多 2000，默认 20）和 offset 进行分页
• 始终返回简要摘要，并截断描述；调用 nvd_get_cve 获取完整详情

---

nvd_get_cve _工具

• 每次调用最多批量查询 100 个 CVE ID
• 完整模式（默认）：v2.0/v3.0/v3.1/v4.0 的 CVSS 分数、CWE 弱点、CPE 配置、CISA KEV 字段、参考链接
• brief: true 返回精简行（ID、状态、最高严重性、KEV 名称、截断的描述）——建议用于超过 10 个 ID 的批量查询
• includeReferences 和 includeConfigurations 默认为 true；将任一项设为 false，即可从两个输出面中省略相应字段。allLanguages: true 会保留所有本地化描述，而非仅保留英文
• 补充字段 missingIds 会列出 NVD 未返回的所有请求 ID
• 两个输出面都会包含所有选定的参考链接和 CPE 配置；如果 NVD 提供了 SSVC 评估，也会显示

---

nvd_search_cpes _工具

• 关键词搜索（例如 "apache http server"）或通过 cpeMatchString 搜索部分 CPEv2.3 模式——至少需要提供其中一项
• 返回完整的 CPE 名称、人类可读的标题、弃用状态和取代它的 CPE
• 使用 limit（最多 10,000，默认 20）和 offset 进行分页——供应商级关键词可能匹配数万条记录，因此应分页查询，而不是进一步缩小范围
• 在使用 nvd_audit_cpe 之前调用此工具，以解析产品所需的确切 CPE 名称

---

nvd_audit_cpe _工具

• 两种模式：精确的 cpeName（NVD 会自动应用 isVulnerable），或带有可选 versionStart/versionEnd 界限的 virtualMatchString（可包含或不包含边界）
• 客户端的 severityMin 会根据所有 CVSS 指标中的最高严重性等级筛选已获取的页面；标题仍依据最高数值分数。它只能删除 limit 获取的结果
• 返回完整的 CVE 记录（CVSS 分数、CWE、CPE 配置、KEV 字段、参考链接）
• includeReferences 和 includeConfigurations 默认为 true；设为 false 会从两个输出面中省略相应字段。SSVC 评估仍为可选
• 使用 limit（最多 2000，默认 20）和 offset 进行分页——每条结果都是完整记录，因此应使用适中的限制值分页，而不是调高限制
• 补充字段 auditTarget 会回显使用的 CPE 标识符，方便调用方确认查询了正确的产品

---

nvd_get_cve_history _工具

• 返回变更事件：CVSS 修订、状态变更、参考链接新增、CPE 配置更新
• order 用于选择锚定端——newest（默认）按最近到最早的顺序读取，oldest 则按 NVD 的原生顺序读取
• 使用 limit（最多 2000，默认 20）和 offset 分页，计数方向从 order 锚定的一端开始
• 不使用 API 密钥时，历史记录端点会显著变慢——请设置 NVD_API_KEY 并提高 NVD_REQUEST_TIMEOUT_MS

---

nvd://cve/{cveId} _资源

• 完整的 CVE 记录，格式为 application/json——数据与单个 ID 的 nvd_get_cve 相同，包含参考资料和仅有英文的描述
• cveId 必须符合 CVE-YYYY-NNNNN 格式；格式正确但未知的 ID 会抛出 cve_not_found

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

NVD 特定功能：

• 请求调度器通过自动排队，强制遵守 NVD 的速率限制：无密钥时为 5 req/30s，有密钥时为 50 req/30s；最小请求间隔根据窗口和限制计算得出
• 重试逻辑位于请求调度器外层，而非内部——每次尝试都会在队列中单独排队，因此重试也会计入速率额度，不会突发超限
• 收到 403 的 Retry-After 后，整个队列会暂停，直到 NVD 的窗口重置；无密钥时，403 会立即失败并指出 NVD_API_KEY，而不是将 5 次请求额度浪费在无法撑过 30 秒窗口的重试上
• 对于确定会被拒绝的请求，会立即失败，不消耗重试次数——NVD 对错误参数和被拒绝的 API 密钥都会返回 HTTP 404，二者仅通过 message 标头区分；因此，被拒绝的密钥会作为配置错误显示，并指出 NVD_API_KEY，而不会被误报为格式错误的 CVE ID
• NVD 屏蔽页面会返回不可重试的请求被屏蔽错误；格式错误的 JSON 和响应信封会返回无效响应错误，并提供恢复指导
• 在读取响应正文期间，请求超时和调用方取消仍然有效

便于 Agent 使用的输出：

• 每个响应都包含 enrichment 块，同时置于 structuredContent 和呈现文本中——包括结果总数、返回数量、页面偏移量、实际应用的筛选条件，以及任何日期调整事件，让 Agent 能够判断实际查询的内容
• 批量 CVE 查找结果包含 missingIds——逐个 ID 进行核对，而不是静默返回不完整结果
• 审计响应会回显 CPE——返回 cpeName 或 virtualMatchString，以便调用方确认审计的产品是否正确
• 无结果提示会说明具体原因——区分查询不匹配、严重性阈值导致页面为空、偏移量超出结果集范围，以及干净的审计（“未发现已知漏洞”），而不会将它们都当作错误或“未找到任何内容”

开始使用

公共托管实例

可使用公共实例：https://nist-nvd.caseyjhand.com/mcp——无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "nist-nvd-mcp-server": {
      "type": "streamable-http",
      "url": "https://nist-nvd.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地部署

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "nist-nvd-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/nist-nvd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NVD_API_KEY": "your-api-key"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "nist-nvd-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/nist-nvd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NVD_API_KEY": "your-api-key"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "nist-nvd-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "NVD_API_KEY=your-api-key",
        "ghcr.io/cyanheads/nist-nvd-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NVD_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 可选：NVD API 密钥——免费，可将速率限制从 5 req/30s 提高到 50 req/30s。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/nist-nvd-mcp-server.git

2. 进入目录：

cd nist-nvd-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set NVD_API_KEY if you have one

配置

变量	描述	默认值
NVD_API_KEY	NVD API 密钥。没有密钥时，速率限制为每 30 秒 5 次请求；使用密钥时为每 30 秒 50 次请求。可在 nvd.nist.gov/developers/request-an-api-key 免费获取。	—
NVD_REQUEST_TIMEOUT_MS	单次请求的超时时间，单位为毫秒。没有 API 密钥时，历史记录端点响应较慢；如果在没有密钥的情况下使用 nvd_get_cve_history，请将其调高至 60000。	10000
NVD_CLAMP_LIMITS	将超出限制的读取数量截断至 2000 个 CVE/事件、10000 个 CPE，或 100 个 CVE ID。设为 false 可恢复架构上限并启用超限拒绝。	true
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_AUTH_MODE	认证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅 Node.js）。	<project-root>/logs
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

完整的可选配置列表请参阅 .env.example。

Node 和 Bun 会在解析服务配置前，从工作目录加载 .env。已导出的变量优先级更高。无效的 NVD_CLAMP_LIMITS 值会导致配置验证失败；请使用 true 或 false。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t nist-nvd-mcp-server .
docker run --rm -e NVD_API_KEY=your-key -p 3010:3010 nist-nvd-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/nist-nvd-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源并初始化服务。
src/config	使用 Zod 解析并验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/services/nvd-http	NVD HTTP 客户端，负责速率限制节流和重试。
src/services/nvd-cve	CVE 服务——搜索、按 ID 获取、CPE 审核、变更历史和规范化。
src/services/nvd-cpe	CPE 服务——字典搜索和规范化。
src/services/nvd-source	来源服务——将 NVD 贡献者标识符解析为其已发布名称。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明如下：

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 进行租户范围内的存储
• 通过 src/mcp-server/*/definitions/index.ts 中的汇总文件注册新工具和资源
• 包装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。