the-real-snipeit-mcp

Talk to Snipe-IT from Claude. Ask "show me all overdue audits", "check out laptop A-42 to manuel", "which licenses expire in the next 90 days" — and the LLM picks the right API call out of 183 tools. Read-and-write, with a safety gate for destructive operations and an envelope-aware client that never mistakes a Snipe-IT error for success.

A Model Context Protocol (MCP) server that exposes the entire Snipe-IT REST API to Claude (Desktop, Code, Agent SDK) over stdio. Built for IT asset managers who'd rather describe what they want than navigate a dashboard.

Three tool layers:

• 38 hand-wrappers (snipeit_*) — friendlier UX for common workflows (checkout/checkin, audits, by-tag/by-serial lookup, bulk checkout)
• ~145 auto-generated tools (snipeit_gen_*) — full coverage of every operation in the OpenAPI 3.1 spec
• snipeit_raw_request — escape hatch for any method/path

Plus 3 resources (current user, settings, asset summary) and 3 prompts (inventory audit, user onboarding, license health).

---

Quick start

Prerequisites: Node ≥ 20, a Snipe-IT instance you can reach (self-hosted or cloud), and an API token from User menu → Manage API Keys (docs).

Option A — Install from npm

npm install -g the-real-snipeit-mcp

Option B — From source

git clone https://github.com/mguttmann/the-real-snipeit-mcp.git
cd the-real-snipeit-mcp
npm install
cp .env.example .env
# edit .env: set SNIPEIT_API_TOKEN and SNIPEIT_API_BASE for your instance
npm run build
npm start    # ← stdio: this blocks; that's normal — your MCP client speaks JSON-RPC over stdin/stdout

Verify with the MCP Inspector (separate terminal):

npm run inspector

⚠️ The SNIPEIT_API_BASE default https://snipe-it.example.com/api/v1 is an RFC 2606 reserved placeholder — it does not resolve. Set your own URL before running.

Configuration

Variable	Default	Description
SNIPEIT_API_TOKEN	(required)	Snipe-IT Personal API Token (JWT)
SNIPEIT_API_BASE	https://snipe-it.example.com/api/v1	API base URL
SNIPEIT_CONFIRM_WRITES	false	If true, destructive tools require confirm: "YES"
SNIPEIT_TIMEOUT_MS	30000	Per-request timeout
SNIPEIT_LOG_LEVEL	info	debug | info | warn | error

Claude Desktop config

{
  "mcpServers": {
    "snipeit": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/the-real-snipeit-mcp/.env",
        "/absolute/path/to/the-real-snipeit-mcp/dist/index.js"
      ]
    }
  }
}

---

Tool reference

Hand-wrappers (38 tools)

Identity (1)

Tool	Endpoint	Annotations
snipeit_me	GET /users/me	readOnly

Hardware / Assets (13)

Tool	Endpoint	Annotations
snipeit_list_hardware	GET /hardware (paginated, common filters)	readOnly
snipeit_search_hardware	GET /hardware?search={query} (convenience)	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}	writeIdempotent
snipeit_checkout_hardware	POST /hardware/{id}/checkout (user/location/asset)	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

Users (5)

Tool	Endpoint	Annotations
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

Licenses (3)

Tool	Endpoint	Annotations
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

Accessories / Consumables / Components (8)

Tool	Endpoint	Annotations
snipeit_list_accessories	GET /accessories	readOnly
snipeit_checkout_accessory	POST /accessories/{id}/checkout	writeOnce
snipeit_checkin_accessory	POST /accessories/{id}/checkin (pivot-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 (to asset)	writeOnce
snipeit_checkin_component	POST /components/{id}/checkin (pivot-id)	writeOnce

Locations / Status-Labels / Maintenances (6)

Tool	Endpoint	Annotations
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

Bulk & Escape (2)

Tool	Behavior	Annotations
snipeit_bulk_checkout	Serially checks out N assets, returns per-item success/error summary	writeOnce
snipeit_raw_request	Any method/path against SNIPEIT_API_BASE — escape hatch	writeOnce (writeIdempotent for GET)

List tools (snipeit_list_*) accept limit?, offset?, and all?: boolean. With all: true, the tool auto-paginates up to 10 000 rows.

Auto-generated tools (snipeit_gen_*)

All 77 paths × every method in the Snipe-IT OpenAPI 3.1 spec are exposed as snipeit_gen_<snake_operation_id> — roughly 145 tools. Use these when the hand-wrapper layer doesn't cover what you need. Read tools have readOnlyHint: true; writes have destructiveHint: true. Regenerate with npm run codegen after npm run refresh-spec.

snipeit_raw_request

Escape hatch for anything else:

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

GET requests bypass the destructive-write guard; other methods honor SNIPEIT_CONFIRM_WRITES.

---

Resources

URI	Description
snipeit://me	Current authenticated user (GET /users/me)
snipeit://settings	Server settings (GET /settings)
snipeit://hardware/summary	{total, by_status_label, by_category} — aggregated counts

Prompts

Prompt	Args	Purpose
snipeit-inventory-audit	–	Lists overdue/due audits + unassigned assets, then summarizes
snipeit-user-onboarding	user_id, optional kit	Suggests a checkout sequence for a new user
snipeit-license-health	–	Seat usage + licenses expiring within 90 days

---

Workflows / Recipes

Onboard a new user with a laptop

1. Confirm the user: snipeit_get_user(id: 42)
2. Find an available laptop: snipeit_list_hardware(category_id: 3, status_id: 5) (ready-to-deploy)
3. Checkout: snipeit_checkout_hardware(id: 100, checkout_to_type: "user", assigned_user: 42, note: "Onboarding 2026-05-25")

Bulk-checkout a kit to one user

{
  "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 }
  ]
}

Continues on per-item errors. Returns {summary: {total, ok, errors}, results: [...]}.

Audit overdue cleanup

1. snipeit_list_audit_overdue(all: true) — full list, auto-paginated
2. For each: snipeit_audit_hardware(asset_tag: "...", location_id: 1, next_audit_date: "2027-05-25")

Find an asset by tag or serial

• By asset tag: snipeit_get_hardware_by_tag(tag: "A-42") (handles URL encoding)
• By serial: snipeit_get_hardware_by_serial(serial: "SN12345")

Discover what an LLM can do

Browse the MCP Inspector:

npm run build && npm run inspector

---

Write safety

By default, destructive tools execute directly. Set SNIPEIT_CONFIRM_WRITES=true and any write tool returns a redacted preview instead — re-invoke with confirm: "YES" to actually execute. Preview includes the full URL (apiBase + path) and a redacted body (password/secret/token/api_key fields replaced with (redacted)).

Snipe-IT API quirk

Snipe-IT often returns HTTP 200 with {"status":"error","messages":…} for validation errors. This server detects that envelope and surfaces the messages as a tool error (with isError: true), so callers never accidentally treat a Snipe-IT error as success. Successful envelopes ({"status":"success","payload":…}) are unwrapped automatically so tool data is the inner payload, not the outer wrapper.

---

Develop

npm run dev               # tsx watch
npm test                  # unit + integration if env present
npm run test:unit         # unit only (CI-safe)
npm run test:integration  # live; requires SNIPEIT_API_TOKEN in .env
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

Security

• API token is read from SNIPEIT_API_TOKEN env only. Never hard-coded. .env is git-ignored.
• The logger redacts known secret patterns (Bearer tokens, JWTs, api_token fields, Authorization header) before any output.
• All MCP stdio output goes to stderr only — stdout is reserved for the protocol.
• If your token has ever been pasted into a chat or commit, rotate it.

License

MIT.