nhtsa-vehicle-safety-mcp-server

公共托管实例： https://nhtsa.caseyjhand.com/mcp

工具

用于查询 NHTSA 车辆安全数据的七个工具：

nhtsa_get_vehicle_safety

综合安全档案——在被问及车辆安全性、可靠性或购车决策时默认使用的工具。

• 在单次响应中结合 NCAP 碰撞安全测试评级、召回历史和投诉摘要。

• 按车型变体返回正面碰撞、侧面碰撞和侧翻评级。

• 召回后果说明，以及“禁止驾驶”“停车室外”和 OTA 更新通知。

• 按零部件细分投诉，含碰撞、火灾、伤害和死亡事故次数。

• 返回 sectionStatus 和警告，避免将上游故障误当作无问题记录。

nhtsa_decode_vin

搜索所需召回活动。

• 按车辆（品牌/型号/年份）或按特定 NHTSA 召回活动编号查找。

• 活动查找返回活动覆盖的每个品牌/型号，以及之前的 ODI 调查。

• 支持 ISO 8601 可选日期范围过滤。

• 包含“禁止驾驶”通知、室外停车警告和 OTA 更新可用状态。

nhtsa_decode_vin

解码车辆识别码以获取制造和安全信息。

• 支持单个 VIN 或批量解码，批量最多 50 个。

• 支持部分 VIN——未知位置用 * 代替。

• 保留稀疏的 VPIC 字段，而不是用空占位符填充缺失数据。

nhtsa_search_investigations

搜索 NHTSA 缺陷调查。

• 调查类型：初步调查（PE）、工程分析（EA）、缺陷申诉（DP）、召回查询（RQ）、审计查询（AQ）等附加 ODI 代码（SQ、EQ、RP 等）。

• 自由文本搜索调查 ID、主题和摘要，并进行结构化厂商、车型与零部件过滤。

• nhtsaId 通过精确 ID 获取一条调查——召回与调查之间的双向呼应。

• 数据来自 NHTSA ODI 批量文件（FLAT_INV.zip）——首次查询会下载并解析（约 10 秒），后续查询使用缓存索引（24 小时 TTL，匹配文件每日刷新）。

• 每页最多返回 25 条调查，响应中回显 offset/limit 和下一页的偏移地址。

nhtsa_search_complaints

搜索提交给 NHTSA 的消费者安全投诉。

• 按零部件明细显示碰撞、起火、伤害和死亡事故次数。

• 可选零部件过滤（例如 "ENGINE"、"AIR BAGS"）。

• 按提交时间排序返回最近 50 条投诉。

• 如果 Event 日期与投诉本身的提交日期或车型（年份）冲突，则披露为 unreliableIncidentDate，而不是将其作为事件日期。

nhtsa_get_safety_ratings

NCAP 碰撞安全测试评级和 ADAS 功能数据。

• 正面碰撞、侧面碰撞（障碍物 + 柱）和侧翻评级。

• ADAS 功能：ESC、前向碰撞预警、车道偏离预警。

• 支持厂家/型号/年份或基于上次 NCAP 结果的 vehicleId。

• 包含现有投诉、召回和调查报告的数量统计。

nhtsa_lookup_vehicles

针对 NHTSA 的 VPIC 数据库进行参考查询。

• 四个操作：makes、models、vehicle_types、manufacturer。

• makes 支持 limit 和 offset 分页，用于完整的 VPIC 目录。

• 用于消除模糊车辆名称或核对拼写。

• 车型可按年份过滤；制造商支持部分名称匹配。

• manufacturer 最多可遍历 500 条 VPIC 记录，并在部分名称匹配命中上限时指出该情况。

Related MCP server: vehicle-safety

功能

基于 @cyanheads/mcp-ts-core：

• 声明式工具定义——每个工具一个文件，框架处理注册和校验。

• 所有工具统一错误处理。

• 可插拔的认证（none、jwt、oauth）。

• 可替换的存储后端：in-memory、filesystem、Supabase、Cloudflare KV/R2/D1。

• 结构化日志，支持可选 OpenTelemetry 追踪。

• 同一套代码既可在本地运行（stdio/HTTP）。

NHTSA 专属：

• 类型安全的客户端，封装四个 NHTSA JSON API，支持重试和稀疏字段归一化，并包含流式解析 ODI 调查批量文件。

• 调查索引缓存（24 小时 TTL），用于快速重复查询。

• 无需 API 密钥——所有 NHTSA API 均公开。

开始使用

公共托管实例

公共实例位于 https://nhtsa.caseyjhand.com/mcp——无需安装。任何 MCP 客户端都可通过 Streamable HTTP 连接：

{
  "mcpServers": {
    "nhtsa-vehicle-safety-mcp-server": {
      "type": "streamable-http",
      "url": "https://nhtsa.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

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

{
  "mcpServers": {
    "nhtsa-vehicle-safety-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/nhtsa-vehicle-safety-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需安装 Bun）：

{
  "mcpServers": {
    "nhtsa-vehicle-safety-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/nhtsa-vehicle-safety-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "nhtsa-vehicle-safety-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/nhtsa-vehicle-safety-mcp-server:latest"]
    }
  }
}

如需 Streamable HTTP，请设置传输类型并启动服务器：

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

先决条件

• Bun v1.3.2 或更高版本（或 Node.js >= 24.0.0）

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/nhtsa-vehicle-safety-mcp-server.git

2. 进入目录：

cd nhtsa-vehicle-safety-mcp-server

3. 安装依赖：

bun install

配置

无需 API 密钥——所有 NHTSA API 均可公开访问。

数据来源

所有数据均来自 NHTSA 的公开 API 和批量文件：

• 召回 API — api.nhtsa.gov/recalls

• 投诉 API — api.nhtsa.gov/complaints

• 安全评级 API — api.nhtsa.gov/SafetyRatings

• 调查批量文件 — static.nhtsa.gov/odi/ffdd/inv/FLAT_INV.zip

• VPIC API — vpic.nhtsa.dot.gov/api/vehicles

运行服务器

本地开发

bun run devcheck  # Lints, formats, type-checks, and more
bun run test      # Runs the test suite

生产

bun run build
bun run start:stdio   # Production stdio
bun run start:http    # Production HTTP

Docker

docker build -t nhtsa-vehicle-safety-mcp-server .
docker run -p 3010:3010 nhtsa-vehicle-safety-mcp-server

项目结构

开发指南

开发指南和架构规则见 CLAUDE.md。简要说明：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch。

• 使用 ctx.log 记录日志。

• 每个文件对应一个工具，工具名统一加 nhtsa_ 前缀。

参与贡献

欢迎提交 Issue 和 Pull Request。提交前请先运行检查：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详见 LICENSE。