Snipe-IT (unofficial)

the-real-snipeit-mcp

一款非官方的 Snipe-IT REST API MCP 服务：为随附的 Snipe-IT OpenAPI 3.1 规范中的每项操作（读写）生成一个工具，为常见工作流提供手写封装，并使用 stdio 传输。

非官方，与 Snipe-IT/Grokability 无关联。 本项目与 Grokability, Inc. 或 Snipe-IT 项目无关联，也未获得其认可、赞助或支持。“Snipe-IT”是其所有者的商标。随附的 API 描述及其许可情况见 NOTICE。

三层工具（183 个）：

• 37 个手写封装（snipeit_*）：为常见工作流提供更友好的使用体验
• 145 个生成的工具（snipeit_gen_*）：随附规范（vendor/snipe-it-rest-api.json，Snipe-IT 8.2.0）中的每项操作对应一个工具
• snipeit_raw_request：用于访问 SNIPEIT_API_BASE 下任意方法和路径的备用入口

另有 3 个资源和 3 个提示词。这些数量由 tests/unit/docsFacts.test.ts 维护。

---

维护状态

• 由一位维护者（@mguttmann）利用业余时间尽力维护。作者在生产环境中通过私有 MCP 网关运行此项目。没有支持合同，也不保证响应时间。
• 安全修复优先于功能开发。请通过 GitHub Private Vulnerability Reporting 私下报告漏洞，切勿在公开 Issue 中报告（见 SECURITY.md）。
• 依赖项更新由 Dependabot 提供；当运行时依赖项存在已知的高危或严重安全公告时，CI 将失败。
• 支持的 Node.js 版本：22.12 或更高版本（见 package.json 中的 engines）；CI 测试 Node 22、24 和 26。
• 仅修复最新的次要版本。发行版及其变更见：CHANGELOG.md。
• 欢迎提交 Issue 和 Pull Request；详见 CONTRIBUTING.md。

安装

需要 Node.js 22.12 或更高版本。服务需要设置 SNIPEIT_API_BASE（你的实例地址，包含 /api/v1）和 SNIPEIT_API_TOKEN；其他变量均为可选项（见配置）。只有 npm 包 the-real-snipeit-mcp 和 MCP Registry 名称 io.github.mguttmann/the-real-snipeit-mcp 属于本项目。

npx（任意 stdio MCP 宿主）

npx 会获取并运行该包；无需克隆或构建。将其连接到 Claude Code（在 Shell 中输入令牌，切勿输入聊天中）：

claude mcp add snipeit \
  -e SNIPEIT_API_BASE=https://snipe-it.example.com/api/v1 \
  -e SNIPEIT_API_TOKEN=<token> \
  -- npx -y the-real-snipeit-mcp

其他任何 stdio 宿主都在其 JSON 配置中使用相同的命令（Claude Desktop：claude_desktop_config.json）：

{
  "mcpServers": {
    "snipeit": {
      "command": "npx",
      "args": ["-y", "the-real-snipeit-mcp"],
      "env": {
        "SNIPEIT_API_BASE": "https://snipe-it.example.com/api/v1",
        "SNIPEIT_API_TOKEN": "<token>"
      }
    }
  }
}

包含这些值的配置文件会保存令牌：请确保只有你的用户能够读取该文件，并且不要将其纳入版本控制。the-real-snipeit-mcp@<version> 用于固定版本。

全局安装

npm install -g the-real-snipeit-mcp

命令为 the-real-snipeit-mcp；在上述宿主配置中将其用作 "command"（不带 args）。

从源代码安装

git clone https://github.com/mguttmann/the-real-snipeit-mcp.git
cd the-real-snipeit-mcp
npm ci
cp .env.example .env
# edit .env: set SNIPEIT_API_BASE and SNIPEIT_API_TOKEN
npm run build        # prebuild runs lint, typecheck and the unit tests first
node --env-file=.env dist/index.js

npm run inspector 会针对构建好的服务启动 MCP Inspector。

用于网关和服务端的固定版本安装

对于无人值守的宿主，请从已提交的锁定文件安装确切版本，不运行安装脚本且不安装开发依赖项，并检查 Registry 签名和来源证明：

mkdir snipeit-mcp && cd snipeit-mcp
npm init -y
npm install --save-exact --ignore-scripts the-real-snipeit-mcp@<version>   # once; commit package.json and package-lock.json
# on every deploy:
npm ci --omit=dev --ignore-scripts
npm audit signatures
node --env-file=/path/to/.env node_modules/the-real-snipeit-mcp/dist/index.js

GitHub Releases 中的每个发行版都包含 npm tarball、CycloneDX SBOM 和 SHA256SUMS；由发布工作流发布的版本还包含 npm 来源声明和 GitHub 构建来源证明。

MCP Registry 和 Glama

每个稳定版本都会以 io.github.mguttmann/the-real-snipeit-mcp 的名称列入官方 MCP Registry（npm 包及其环境变量）。glama.json 列出了 Glama 页面维护者的名称。

配置

变量	默认值	描述
SNIPEIT_API_TOKEN	（必填）	Snipe-IT Personal API Token（JWT）
SNIPEIT_API_BASE	https://snipe-it.example.com/api/v1	API 基础 URL。默认值是 RFC 2606 占位符；请设置为你的实例地址。服务器会在任何有效 URL 下启动，但在使用占位符、http 指向非环回主机（令令牌以明文传输）、使用其他协议、URL 中含凭据或 URL 带有查询参数或片段时，会记录警告
SNIPEIT_CONFIRM_WRITES	true	若启用（默认），破坏性工具必须提供 confirm: "YES"。只有 false、0、no 或 off（不区分大小写）会关闭保护；空值或无法识别的值会保持启用状态并记录警告。启动时会将生效状态记录到 stderr
SNIPEIT_TIMEOUT_MS	30000	每次尝试的超时时间（毫秒，正整数），涵盖响应头和完整的响应正文读取
SNIPEIT_LOG_LEVEL	info	debug | info | warn | error
SNIPEIT_MAX_RESULT_BYTES	1048576（1 MiB）	单个工具结果（序列化 JSON，字节数）的上限；最小值为 65536。超过 8 MiB 时会记录警告：TypeScript SDK 客户端每条消息最多读取 10 MiB。较大的结果会缩短为有效 JSON，并带有截断标记（参见大型和二进制结果）。单个 HTTP 响应正文的缓冲大小绝不会超过 16 MiB 与此值 4 倍两者中的较大值。
SNIPEIT_CALL_DEADLINE_MS	0（无）	单次工具调用的总截止时间（毫秒），涵盖重试、退避以及 all: true 分页；0 表示禁用。调用超过截止时间时会以 DEADLINE_EXCEEDED 工具错误结束；all: true 会返回截至目前收集的行，并设置 truncated: true 和 next_offset
SNIPEIT_REDACT_PII	false	在工具结果和资源读取中使用 (redacted) 屏蔽个人数据（错误文本和写入预览中除外）：任意深度的 email、employee_num(ber)、phone、mobile、address、address2、username、first_name、last_name，以及描述人物的对象的 name。资产、型号和地点名称会保留。接受 true/false（也接受 1/0、yes/no、on/off）；无法识别的值会启用此功能并记录警告
SNIPEIT_REDACT_SECRETS	false	在工具结果和资源中使用 (redacted) 屏蔽机密：任意深度下键名匹配 password|secret|token|api[_-]?key 的所有值；以及每个 custom_fields 条目（对象或数组形式）中，其显示名称或数据库列（_snipeit_*，写入响应中也包括扁平键）匹配 passw|kennw|secret|token|key|recovery|bitlocker|pin|laps（不区分大小写；故意采用宽泛匹配，因此“Keyboard layout”也会被屏蔽）的 value；还包括每个 log_meta 条目（操作日志、/reports/activity）的 old 和 new，以及名称或列符合任一规则的每个自定义字段定义的 default_value。空值和空字符串会保留。回显此类 JSON 字段的错误文本也会被屏蔽。接受的值与 SNIPEIT_REDACT_PII 相同；无法识别的值会启用此功能并记录警告。写入工具始终拒绝包含此占位符的正文（参见写入安全）
SNIPEIT_READ_ONLY	false	在运行时拒绝所有写入，并返回 READ_ONLY 工具错误；所有工具仍会注册，读取操作正常。接受的值与 SNIPEIT_REDACT_PII 相同；无法识别的值会启用此功能
SNIPEIT_REQUIRE_PREVIEW	false	写入保护启用时，只有在最近 10 分钟内预览过完全相同的请求，且每次预览仅使用一次后，confirm: "YES" 才会执行。关闭时，首次调用即会执行 confirm: "YES"。接受的值与 SNIPEIT_REDACT_PII 相同

变量可来自环境、node --env-file=<file>，或工作目录中的 .env（或 DOTENV_CONFIG_PATH 指定的文件）；这些来源绝不会覆盖已设置的变量。启动时会将 .env 新增的变量名称（不会记录其值）写入 stderr。

---

工具参考

手动封装工具（37 个）

身份（1）

工具	端点	注释
snipeit_me	GET /users/me	readOnly

硬件 / 资产（13）

工具	端点	注释
snipeit_list_hardware	GET /hardware（分页，常用筛选条件）	readOnly
snipeit_search_hardware	GET /hardware?search={query}（便捷方式）	readOnly
snipeit_get_hardware_by_id	GET /hardware/{id}	readOnly
snipeit_get_hardware_by_tag	GET /hardware/bytag/{tag}	readOnly
snipeit_get_hardware_by_serial	GET /hardware/byserial/{serial}	readOnly
snipeit_create_hardware	POST /hardware	writeOnce
snipeit_update_hardware	PATCH /hardware/{id}	writeIdempotent
snipeit_delete_hardware	DELETE /hardware/{id}（软删除；snipeit_gen_hardwareidrestore 可恢复）	writeIdempotent
snipeit_checkout_hardware	POST /hardware/{id}/checkout（用户/位置/资产）	writeOnce
snipeit_checkin_hardware	POST /hardware/{id}/checkin	writeOnce
snipeit_audit_hardware	POST /hardware/audit	writeOnce
snipeit_list_audit_due	GET /hardware/audit/due	readOnly
snipeit_list_audit_overdue	GET /hardware/audit/overdue	readOnly

用户（5）

工具	端点	注释
snipeit_list_users	GET /users	readOnly
snipeit_get_user	GET /users/{id}	readOnly
snipeit_get_user_assets	GET /users/{id}/assets	readOnly
snipeit_get_user_accessories	GET /users/{id}/accessories	readOnly
snipeit_get_user_licenses	GET /users/{id}/licenses	readOnly

许可证（3）

工具	端点	注释
snipeit_list_licenses	GET /licenses	readOnly
snipeit_get_license_seats	GET /licenses/{id}/seats	readOnly
snipeit_checkout_license_seat	PUT /licenses/{license_id}/seats/{seat_id}	writeIdempotent

配件 / 耗材 / 组件（8）

工具	端点	注释
snipeit_list_accessories	GET /accessories	readOnly
snipeit_checkout_accessory	POST /accessories/{id}/checkout	writeOnce
snipeit_checkin_accessory	POST /accessories/{id}/checkin（关联记录 ID）	writeOnce
snipeit_list_consumables	GET /consumables	readOnly
snipeit_checkout_consumable	POST /consumables/{id}/checkout	writeOnce
snipeit_list_components	GET /components	readOnly
snipeit_checkout_component	POST /components/{id}/checkout（分配给资产）	writeOnce
snipeit_checkin_component	POST /components/{id}/checkin（关联记录 ID）	writeOnce

位置 / 状态标签 / 维护（6）

工具	端点	注释
snipeit_list_locations	GET /locations	readOnly
snipeit_get_location	GET /locations/{id}	readOnly
snipeit_list_statuslabels	GET /statuslabels	readOnly
snipeit_get_statuslabel_assets	GET /statuslabels/{id}/assetlist	readOnly
snipeit_list_maintenances	GET /maintenances	readOnly
snipeit_create_maintenance	POST /maintenances	writeOnce

批量（1）

工具	行为	注释
snipeit_bulk_checkout	按顺序分配最多 100 项资产，返回逐项成功/错误摘要；取消时会在处理下一项前停止，并报告 aborted 和 not_attempted；将每项已执行操作（asset_id、结果、HTTP 状态）记录到 stderr	writeOnce

列表工具（snipeit_list_*）接受 limit?、offset? 和 all?: boolean。设置 all: true 后，工具会自动分页，最多获取 10 000 行，或在结果大小可能超过 SNIPEIT_MAX_RESULT_BYTES 时停止；此时会返回已收集的行，并附带 truncated: true、next_offset 和 total，你可以继续使用 limit/offset 获取后续结果。

自动生成的工具（snipeit_gen_*）

随附的 Snipe-IT OpenAPI 3.1 规范中的每个操作（路径和方法）都会公开为 snipeit_gen_<snake_operation_id>。每个标题的格式为 METHOD /path，每条描述都以 METHOD /path: 开头，后接规范中对该操作的描述。两个文件上传操作（POST /hardware/{id}/files、POST /models/{id}/files）无法上传：随附的规范声明了 JSON 请求体，而 Snipe-IT 需要 multipart/form-data；其描述中已说明这一点。如果手动封装层未涵盖所需功能，请使用这些工具。GET 工具的 readOnlyHint: true；其他所有方法的 destructiveHint: true，并会经过写入保护。运行 npm run refresh-spec 后，再通过 npm run codegen 重新生成。

snipeit_raw_request

用于处理其他情况的逃生通道：

{ method: "PATCH", path: "/locations/4", body: { name: "HQ" } }

对于所有方法，其注释均为静态值（destructiveHint: true、idempotentHint: false）。GET 请求会绕过写入保护；其他方法遵循 SNIPEIT_CONFIRM_WRITES。路径必须以单个 / 开头；绝对 URL 和超出 SNIPEIT_API_BASE 范围的路径都会被拒绝。

---

资源

URI	描述
snipeit://me	当前已认证用户（GET /users/me）
snipeit://settings	服务设置（GET /settings）。此端点不在随附的 8.2.0 规范中；如果实例未提供此端点，资源会返回 {error, note}，而非读取失败
snipeit://hardware/summary	{total, by_status_label, by_category}：汇总计数，每次最多发出 6 个计数请求。计数失败时（例如遭遇 API 限流），其值为 -1，此时结果会附带 partial: true 和 errors[]

提示词

提示词	参数	用途
snipeit-inventory-audit	无	列出逾期/到期审计项和未分配资产，然后进行汇总
snipeit-user-onboarding	user_id、可选的 kit	为新用户推荐一套领用流程
snipeit-license-health	无	座席使用情况，以及 90 天内到期的许可证

---

工作流 / 配方

为新用户配备笔记本电脑

1. 确认用户：snipeit_get_user(id: 42)
2. 查找可用笔记本电脑：snipeit_list_hardware(category_id: 3, status_id: 5)（可部署状态）
3. 办理领用：snipeit_checkout_hardware(id: 100, checkout_to_type: "user", assigned_user: 42, note: "Onboarding 2026-05-25")

向一位用户批量办理套件领用

{
  "items": [
    { "asset_id": 100, "checkout_to_type": "user", "assigned_user": 42 },
    { "asset_id": 101, "checkout_to_type": "user", "assigned_user": 42 },
    { "asset_id": 102, "checkout_to_type": "user", "assigned_user": 42 }
  ]
}

遇到单项错误时会继续处理。返回 {summary: {total, ok, errors}, results: [...]}。

清理逾期审计项

1. snipeit_list_audit_overdue(all: true)：获取完整列表，自动翻页
2. 对每项执行：snipeit_audit_hardware(asset_tag: "...", location_id: 1, next_audit_date: "2027-05-25")

按资产标签或序列号查找资产

• 按资产标签：snipeit_get_hardware_by_tag(tag: "A-42")（会处理 URL 编码）
• 按序列号：snipeit_get_hardware_by_serial(serial: "SN12345")

查看 LLM 能执行的操作

浏览 MCP Inspector：

npm run build && npm run inspector

---

写入安全

默认情况下，写入保护已开启：所有带有 destructiveHint: true 的工具都会返回脱敏预览，而不执行操作；使用 confirm: "YES" 重新调用即可执行。预览会列出工具、方法、URL、查询参数和已脱敏的请求体（密码、密钥、令牌、api_key 字段会替换为 (redacted)）；snipeit_bulk_checkout 会列出每个具体请求。预览是正常结果，不是错误：其文本包含 status: "preview"，其 _meta 携带 "snipeit/preview": true，因此客户端无需解析内容即可区分预览和已执行的写入。每个写入工具都会显示完整 URL（SNIPEIT_API_BASE + 路径）。

只有将 SNIPEIT_CONFIRM_WRITES 设为 false、0、no 或 off（会先去除首尾空格，且不区分大小写）时，才会禁用保护并让写入工具直接执行。未设置、设为 true/1/yes/on、空值或其他任何值都会保持保护开启；空值或无法识别的值还会记录一条警告。启动时，有效状态会记录到 stderr 一次。

confirm 由模型设置，因此该保护能拦截忘记设置它的模型，但无法拦截在 Snipe-IT 数据中添加该字段的提示词注入；人工审批必须由 MCP 主机或网关完成。以下两个可选开关可在服务端加强保护：

• SNIPEIT_READ_ONLY=true 会拒绝所有写入，并返回 READ_ONLY 工具错误；所有工具仍会注册（工具列表不会改变），读取操作正常，包括使用 GET 调用的 snipeit_raw_request。
• SNIPEIT_REQUIRE_PREVIEW=true（且保护已开启）要求先在最近 10 分钟内预览完全相同的请求，之后才会执行 confirm: "YES"；每次预览只能用于一次执行，因此每次写入都必须先预览。

无论这些设置如何配置，所有写入工具（手写工具、生成的工具、snipeit_bulk_checkout，以及使用 GET 以外方法的 snipeit_raw_request）都会拒绝请求体或查询中任何值恰好为 (redacted) 的请求；检查范围包括对象和数组的任意嵌套深度，并且不受 SNIPEIT_REDACT_SECRETS 和 SNIPEIT_REDACT_PII 设置影响。工具会在预览、SNIPEIT_READ_ONLY 检查和发送请求之前返回工具错误，其中包含 details.code: "REDACTED_PLACEHOLDER" 和 details.paths（例如 body.custom_fields["BitLocker Key"].value、body[2].password、items[2].note、query.token），以防止开启脱敏的资产读取结果在原样写回时将恢复密钥覆盖为占位符。仅包含 (redacted) 的字符串仍会照常发送。请设置真实值或省略该字段。

每次预览、拒绝和已确认的执行都会记录一条 info 日志（工具、方法、URL）；每个已执行的写入请求还会记录一条包含 HTTP 状态码的 info 日志（不包含查询参数或请求体）。

Snipe-IT API 特殊行为

Snipe-IT 在验证失败时经常返回 HTTP 200，并附带 {"status":"error","messages":…}。此服务会检测该响应结构，并将其中的消息作为工具错误返回（包含 isError: true），从而避免调用方误将 Snipe-IT 错误当作成功。成功的响应结构（{"status":"success","payload":…}）会自动解包，因此工具数据是内部的 payload，而非外层封装。

大型和二进制结果

• 大小上限。 每个工具结果都限制为 SNIPEIT_MAX_RESULT_BYTES（默认值为 1 MiB）。列表（{total, rows}）会保留能容纳的前几行，并添加 truncated: true 和 next_offset；分页提示也会相应调整。顶层数组会保留前几个条目，并在 data 旁添加一个 truncated 对象。其他任何超大结果都会替换为 {truncated: true, size_bytes, max_result_bytes, note}。输出始终是有效 JSON，不会出现被截断的字符串。
• 响应正文读取上限。 单个 HTTP 响应正文的读取上限为 16 MiB 与 SNIPEIT_MAX_RESULT_BYTES 的 4 倍二者中的较大值。超出上限的 JSON 或文本正文会触发 RESPONSE_TOO_LARGE 工具错误，而不会被缓冲。
• 二进制下载。 对于内容类型不是 JSON、XML 或 text/* 的响应（例如备份 zip、已上传的文件、图片、PDF），不会进行解码。工具会返回 {binary: true, content_type, size_bytes, size_exact, filename, note}；如果需要文件内容，请直接从 Snipe-IT 下载。
• 超时、重试、重定向。 SNIPEIT_TIMEOUT_MS 限制每次尝试的时长，包括读取正文的时间。始终会重试 429；对于幂等方法（GET、PUT、DELETE），才会重试 5xx 和网络错误；POST 和 PATCH 仅在连接从未建立时（ECONNREFUSED、ENOTFOUND、EAI_AGAIN）重试，因此写入操作绝不会发送两次。永不跟随重定向。取消的工具调用（MCP 取消或客户端已关闭）会立即中止其 HTTP 请求和任何重试等待；SNIPEIT_CALL_DEADLINE_MS 可选用于限制整个调用的时长。

---

开发

npm run dev               # tsx watch
npm test                  # unit; live tests only with SNIPEIT_LIVE_TESTS=1
npm run test:contract     # gateway tool contract + protocol revisions
npm run test:unit         # unit only (CI-safe)
SNIPEIT_LIVE_TESTS=1 npm run test:integration  # live; also needs SNIPEIT_API_TOKEN
npm run lint
npm run typecheck
npm run codegen           # regenerate src/tools/generated from vendor/snipe-it-rest-api.json
npm run refresh-spec      # pull latest OpenAPI spec from snipe-it.readme.io
npm run inspector         # MCP Inspector

有关分层图和数据流，请参阅 ARCHITECTURE.md。有关添加手动封装器、重新生成代码生成层和调试的信息，请参阅 CONTRIBUTING.md。

安全

• API 令牌仅从 SNIPEIT_API_TOKEN 环境变量读取，绝不硬编码。.env 已列入 git 忽略列表。
• 0.1.7 及更早版本可通过带有绝对 URL 的 snipeit_raw_request 将令牌发送到其他主机；请升级到 0.2.0 或更高版本（参见 CHANGELOG.md）。
• 日志记录器以及返回给模型的所有错误文本，都会对已知机密模式进行脱敏（Bearer 令牌、JWT、任何方案的 Authorization 标头、api_token/password/secret/token/api_key 字段和查询参数、URL 用户信息）。
• 工具结果会将 Snipe-IT 数据（包括用户的个人数据，如姓名、电子邮件地址、员工编号）传递给 MCP 客户端及其模型提供商。SNIPEIT_REDACT_PII=true 会屏蔽这些字段；参见 SECURITY.md。
• 工具结果也可能包含 Snipe-IT 存储在自定义字段中的机密（恢复密钥、本地管理员密码）。SNIPEIT_REDACT_SECRETS=true 会屏蔽工具结果和资源中名称含机密的字段以及机密自定义字段值；参见 SECURITY.md。
• 每个请求都会固定到 SNIPEIT_API_BASE 的源和路径；永不跟随重定向（任何 3xx 都会变成工具错误，并指出状态码和 Location），因此，配置错误的基准 URL（例如，HTTPS 重定向后仍使用 http://）会明确报错，而不会让写入操作悄然变成 GET。
• 所有日志输出仅写入 stderr；stdout 专用于 MCP 协议。
• 如果你曾将令牌粘贴到聊天或提交中，请立即轮换令牌。

许可证

MIT（参见 LICENSE）。随附的 Snipe-IT API 描述不受其许可；参见 NOTICE。