mcp-server-snipeit

MCP server for the Snipe-IT asset management system

console application
Install
apt install mcp-server-snipeit
Description

An MCP (Model Context Protocol) server that exposes the Snipe-IT REST API as tools for an LLM agent, built on fastmcp. It runs over stdio and is registered into a local mcprack catalog by its companion package.

Tools cover assets, consumables, accessories, components, licenses, users, locations, models, kits, custom fields, imports and reports. A read-only mode refuses every state-changing action.

๐ŸŒ Homepage๐Ÿ“ฆ GitHub๐Ÿ› Issues๐Ÿ“‹ Package details

Snipe-IT MCP Server

A comprehensive Model Context Protocol (MCP) server for managing Snipe-IT inventory systems. This server enables AI assistants to perform full CRUD operations across your entire Snipe-IT instance with 40 tools covering all major API endpoints, plus 2 optional data-quality tools that use a judgment model โ€” TypeSafe Jev, a self-hosted open-weight System One model such as Laya, or an OpenAI-compatible chat model via Ollama โ€” for duplicate detection and record matching.

Features

Asset Management

  • Full CRUD Operations: Create, read, update, delete, and search assets with enhanced filtering
  • Barcode/Serial Lookup: Direct bytag/byserial API endpoints for reliable barcode scanning
  • Asset Operations: Checkout, checkin, audit, and restore assets
  • Checkout Requests: Submit and cancel checkout requests for requestable assets
  • File Attachments: Upload, download, list, and delete asset files
  • Label Generation: Generate printable PDF labels
  • Maintenance Tracking: Create and manage maintenance records
  • License Associations: View licenses assigned to assets

Inventory Tracking

  • Consumables: Complete management of consumable items
  • Components: Manage components with checkout/checkin to assets
  • Accessories: Track accessories with checkout/checkin to users, assets, or locations

Users & Organization

  • Users: Full user management including restore and current user endpoint
  • User Assets: View all items checked out to a user (assets, accessories, licenses, consumables, EULAs)
  • Two-Factor Auth: Reset user 2FA (admin function)
  • Companies: Multi-tenant company management
  • Departments: Organizational department management
  • Groups: Permission group management

System Configuration

  • Categories: Manage categories for all item types
  • Manufacturers: Track manufacturer information
  • Models: Define asset models with depreciation, custom fields, and file attachments
  • Status Labels: Configure asset statuses with asset listing
  • Locations: Manage physical locations with hierarchy, asset/user queries
  • Suppliers: Track supplier information
  • Depreciations: Define depreciation schedules

Custom Fields

  • Fields: Create and manage custom field definitions
  • Fieldsets: Group custom fields for assignment to models with field reordering
  • Field Association: Associate/disassociate fields with fieldsets

Licensing

  • License Management: Full CRUD for software licenses
  • Seat Assignments: Checkout/checkin license seats
  • License Files: Manage license documentation

Reporting & Auditing

  • Activity Logs: Query all activity history
  • Item Activity: Get activity for specific items
  • Status Summary: Asset counts grouped by status label
  • Audit Tracking: Track assets due/overdue for audit

Data Quality (optional, judgment-model backed)

  • Duplicate Detection: Find likely duplicate manufacturers, models, suppliers, locations, categories, companies, or departments โ€” judged pairwise with a confidence per pair
  • Record Matching: Resolve free-text names (CSV cells, spoken descriptions) to existing record IDs, with an explicit "none" abstention
  • Bring your own model: TypeSafe Jev (hosted), any self-hosted server speaking the System One protocol (Laya, CLM, โ€ฆ), or any OpenAI-compatible chat server (Ollama, vLLM, LM Studio, โ€ฆ)
  • Enabled only when a backend is configured; see Optional โ€” judgment backend for the data-quality tools

Import & System Administration

  • CSV Imports: Full import workflow (upload, map columns, process)
  • System Info: Get Snipe-IT version information
  • Backups: List and download database backups
  • LDAP Operations: LDAP sync and connection testing

Debian / mcprack (Vitexus fork)

This fork is packaged for Debian/Ubuntu (trixie) as mcp-server-snipeit and registers into mcprack via the companion mcprack-mcp-server-snipeit (registered with SNIPEIT_READ_ONLY=true).

sudo apt install mcp-server-snipeit mcprack-mcp-server-snipeit

The binary is /usr/bin/mcp-server-snipeit (snipeit-mcp is kept as an alias). It needs python3-fastmcp (>= 4.1.4) and python3-snipeit-api (>= 0.5.2). Upstream base: jameshgordy/snipeit-mcp 2.0.1 (2e35de1, 2026-11-13).

Read-only mode

SNIPEIT_READ_ONLY=true refuses every state-changing action (create, update, delete, checkout, checkin, audit, restore, upload, sync, ...). Snipe-IT tools are multiplexed by an action argument, so tools stay listed and the write actions are rejected.

Environment variables

Variable Secret Purpose
SNIPEIT_URL no Snipe-IT base URL (required)
SNIPEIT_TOKEN yes API token (single-identity mode)
SNIPEIT_READ_ONLY no Refuse state-changing actions
SNIPEIT_ALLOWED_TOOLS no Tool allowlist
MCP_TRANSPORT, MCP_HOST, MCP_PORT no Transport (stdio default)
MCP_TOKEN yes Bearer token for the http transport
SNIPEIT_OAUTH_CLIENT_ID, SNIPEIT_OAUTH_CLIENT_SECRET, SNIPEIT_MCP_BASE_URL, SNIPEIT_MCP_REDIRECT_PATH, SNIPEIT_OAUTH_CACHE_TTL, SNIPEIT_OAUTH_TIMEOUT secret: client secret OAuth mode
SNIPEIT_IDENTITIES_FILE no Multi-identity registry
LOG_LEVEL no Log level
JUDGMENT_BACKEND, JUDGMENT_BASE_URL, JUDGMENT_MODEL, JUDGMENT_API_KEY, JUDGMENT_SAMPLES, JUDGMENT_TIMEOUT, JUDGMENT_TIME_BUDGET JUDGMENT_API_KEY Data-quality judgment backend

Tool annotation classes

All tools carry a title and all four annotation hints (src/mcp_server_snipeit/annotations.py). Read-only: system_info, asset_licenses, user_assets, activity_reports, status_summary, audit_tracking, data-quality tools. Create-like: asset_operations, asset_labels, asset_requests, license_seats, ldap_operations, ... Everything named manage_* is classified destructive (it can delete). The authoritative list is debian/server.json.

Requirements

  • Python 3.11+
  • UV package manager
  • Snipe-IT instance with API access
  • API token with appropriate permissions

Installation

1. Clone the repository

git clone https://github.com/jameshgordy/snipeit-mcp.git
cd snipeit-mcp

2. Install dependencies

uv sync

3. Configure environment variables

The server supports two authentication modes; pick one.

Mode A โ€” API key (stdio or HTTP, single shared identity)

Create a .env file:

SNIPEIT_URL=https://your-snipeit-instance.com
SNIPEIT_TOKEN=your-api-token-here
SNIPEIT_ALLOWED_TOOLS=manage_assets,system_info  # Optional: restrict exposed tools
Variable Required Description
SNIPEIT_URL Yes Your Snipe-IT instance URL
SNIPEIT_TOKEN Yes API token for authentication
SNIPEIT_ALLOWED_TOOLS No Comma-separated list of tool names to expose. If unset, all tools are available.

Getting an API Token:

  1. Log in to your Snipe-IT instance
  2. Navigate to your user profile (top right menu)
  3. Go to "Manage API Keys" or "Personal Access Tokens"
  4. Generate a new token with required permissions

Mode B โ€” Interactive OAuth login (HTTP only, per-user identity)

In this mode the MCP server runs as a web service and acts as an OAuth proxy in front of Snipe-IT's built-in Laravel Passport provider. Each user logs in to Snipe-IT (going through your normal SAML / SSO if configured) and the MCP server uses that user's own access token for every tool call.

One-time Snipe-IT setup (admin):

  1. Visit https://your-snipeit-instance.com/admin/oauth
  2. Create a new OAuth client
  3. Set the redirect URI to https://your-mcp-public-url/auth/callback
  4. Note the generated client ID and secret

Environment variables:

SNIPEIT_URL=https://your-snipeit-instance.com
SNIPEIT_OAUTH_CLIENT_ID=...                  # from /admin/oauth
SNIPEIT_OAUTH_CLIENT_SECRET=...              # from /admin/oauth
SNIPEIT_MCP_BASE_URL=https://your-mcp-public-url
MCP_TRANSPORT=http
MCP_PORT=8000
# MCP_HOST=0.0.0.0                            # defaults to 127.0.0.1
Variable Required Description
SNIPEIT_URL Yes Your Snipe-IT instance URL
SNIPEIT_OAUTH_CLIENT_ID Yes OAuth client ID from /admin/oauth
SNIPEIT_OAUTH_CLIENT_SECRET Yes OAuth client secret from /admin/oauth
SNIPEIT_MCP_BASE_URL Yes Public URL where this MCP server is reachable (used in the OAuth callback)
SNIPEIT_MCP_REDIRECT_PATH No Override OAuth callback path (default /auth/callback)
MCP_TRANSPORT Yes Must be http for OAuth mode
MCP_HOST No Bind address (default 127.0.0.1; use 0.0.0.0 behind a reverse proxy)
MCP_PORT Yes TCP port for the HTTP server
LOG_LEVEL No DEBUG/INFO/WARNING/ERROR/CRITICAL (default INFO)

[!NOTE] OAuth mode requires HTTP transport โ€” starting with MCP_TRANSPORT=stdio while OAuth env vars are set fails at startup with a clear error.

Mode C โ€” multi-identity (HTTP, one container, per-user tokens)

In this mode one container serves all people, each still acting under their own Snipe-IT personal access token. Instead of one container per person (each with a private SNIPEIT_TOKEN), every person gets a random MCP token that they put into their own MetaMCP server entry. The server maps MCP token โ†’ identity โ†’ Snipe-IT PAT per request, so the Snipe-IT activity log shows the correct person for every action, and the container log carries a second, Snipe-IT-independent audit trail.

Mode C requires HTTP transport and is mutually exclusive with OAuth mode (startup fails if both are configured).

Per-person tokens: generate one random token per person, e.g. openssl rand -hex 32. Tokens must be at least 32 characters, unique per person, and different from that person's Snipe-IT PAT (startup validates all of this and exits with a clear error otherwise).

Environment variables:

SNIPEIT_URL=https://your-snipeit-instance.com   # one instance for all
# One block per person (<KEY> matches [A-Z0-9_]+, e.g. STAAT):
SNIPEIT_IDENTITY_STAAT_MCP_TOKEN=...            # required, >= 32 chars, unique
SNIPEIT_IDENTITY_STAAT_SNIPEIT_TOKEN=...        # required, the person's Snipe-IT PAT
SNIPEIT_IDENTITY_STAAT_DISPLAY_NAME=...         # optional, shown in logs
SNIPEIT_IDENTITY_STAAT_ALLOWED_TOOLS=...        # optional CSV, e.g. manage_assets,system_info
SNIPEIT_IDENTITY_STAAT_READ_ONLY=true           # optional, blocks all write actions
# Transport (required for this mode):
MCP_TRANSPORT=http
MCP_PORT=8000
MCP_HOST=127.0.0.1
Variable Required Description
SNIPEIT_URL Yes Snipe-IT instance URL (shared by all identities)
SNIPEIT_IDENTITY_<KEY>_MCP_TOKEN Yes Random bearer token the person uses to authenticate to this MCP server (min 32 chars, unique per person)
SNIPEIT_IDENTITY_<KEY>_SNIPEIT_TOKEN Yes That person's Snipe-IT personal access token
SNIPEIT_IDENTITY_<KEY>_DISPLAY_NAME No Human-readable name used in log lines (identity keys are logged at startup, never token values)
SNIPEIT_IDENTITY_<KEY>_ALLOWED_TOOLS No Comma-separated tool allowlist for that person; enforced at call time and in tools/list
SNIPEIT_IDENTITY_<KEY>_READ_ONLY No When true, blocks all write actions (create, update, delete, checkout, checkin, audit, restore, file uploads, imports, LDAP sync, โ€ฆ); read actions stay allowed
SNIPEIT_IDENTITIES_FILE No Path to a JSON file with the same fields (list of objects with an explicit key). If set, the file wins and all SNIPEIT_IDENTITY_* env vars are ignored (logged at startup). For secret-mount based environments.
MCP_TRANSPORT Yes Must be http
MCP_PORT Yes TCP port for the HTTP server
MCP_HOST No Bind address (default 127.0.0.1)
LOG_LEVEL No DEBUG/INFO/WARNING/ERROR/CRITICAL (default INFO)

MetaMCP configuration โ€” one entry per person: the only difference between the entries is the bearer token; the URL is identical for everyone.

MetaMCP server entry (per person, Ownership: Private)
  Name:         snipeit
  Type:         Streamable HTTP
  URL:          http://snipeit-mcp:8000/mcp        โ† identical for all
  Bearer Token: <that person's MCP token>          โ† the only difference

How a request is handled:

  1. The HTTP layer checks Authorization: Bearer <mcp_token>. Missing or unknown token โ†’ 401 with WWW-Authenticate: Bearer, before any tool runs. Token comparison is constant-time (hmac.compare_digest).
  2. The identity is stored in a request-scoped context variable; the tool call then authenticates to Snipe-IT with that person's PAT.
  3. One JSON audit line per tool call goes to stderr (logger mcp_server_snipeit.audit): identity, tool, action, outcome, duration, and a SHA-256 digest of the arguments (arguments themselves are never logged, and no token ever appears in logs).
{"ts":"2026-08-26T09:41:02.113456+00:00","identity":"STAAT","tool":"manage_assets","action":"update","ok":true,"duration_ms":142,"args_digest":"9f2c1ab04e6d7731"}

Health endpoint: unauthenticated GET /healthz returns {"status":"ok","identities":<n>} โ€” use it for container healthchecks (see deploy/docker-compose.yml).

[!WARNING] Known, accepted limitations โ€” read before deploying:

  • The container still holds all people's PATs in environment variables. Whoever can read them (Portainer admin, Docker host access) can impersonate any identity. Per-request attribution becomes robust, but it is not tamper-proof.
  • One container for everyone is a single point of failure for all of them โ€” if it goes down, nobody's Snipe-IT access via MCP works.
  • Bearer-token authentication only protects traffic that stays on the internal Docker network. Do not publish the port to a wider network (the compose file deliberately has no ports: mapping).
  • Only OAuth mode (Mode B) provides cryptographically sound per-user attribution, and it does not fit centrally managed clients like MetaMCP.

Optional โ€” judgment backend for the data-quality tools

The two data-quality tools, find_duplicates and match_records, ask typed questions โ€” "are these two records the same manufacturer?" (a 3-level score), "which of these models does this text refer to?" (a choice with a none option) โ€” and need a model to answer them with a probability per option. They are hidden from tools/list until a backend is configured, so an unconfigured server presents exactly the 40 core tools. They work in every auth mode and are read-only with respect to Snipe-IT.

Backend (JUDGMENT_BACKEND) Works with Confidence Speed / cost
systemone (default) TypeSafe Jev (hosted, needs a key from console.typesafe.ai); self-hosted open-weight System One models that serve the same POST /v1/systemone protocol โ€” Laya (Apache 2.0, ~400M params), CLM-8B, Rapid-MLX's system-one server, openjev Calibrated probabilities; the thresholds below are meaningful ~0.1 s per question set; Jev is ~$0.04 per million input tokens, self-hosted is free
openai Any OpenAI-compatible /chat/completions server with JSON-schema structured outputs: Ollama (โ‰ฅ 0.5), vLLM, LM Studio, llama.cpp server, OpenRouter, OpenAI Not calibrated: the model's self-reported confidence, or vote frequency across JUDGMENT_SAMPLES runs Seconds per question set on a local 8B model; a 100-pair scan is minutes, not seconds

[!NOTE] Only the hosted TypeSafe API has been exercised for wire-format compatibility (against the official SDK's source). The self-hosted System One servers and the chat backend have been tested against mocked HTTP only โ€” please report what works for you.

TypeSafe Jev (hosted):

TYPESAFE_API_KEY=...                          # the typesafe-sdk variable name is accepted as-is
#TYPESAFE_DEFAULT_MODEL=jev-1.13.0            # pin a version once thresholds are tuned

Self-hosted System One model (e.g. Laya):

JUDGMENT_BACKEND=systemone
JUDGMENT_BASE_URL=http://laya:8080            # must serve POST /v1/systemone
JUDGMENT_MODEL=laya

Ollama (or any OpenAI-compatible server):

JUDGMENT_BACKEND=openai
JUDGMENT_BASE_URL=http://localhost:11434/v1   # Ollama's OpenAI-compatible base (default)
JUDGMENT_MODEL=qwen3:8b                       # any pulled model that follows JSON schemas well
#JUDGMENT_SAMPLES=3                           # optional: vote across 3 samples instead of self-reported confidence
#JUDGMENT_API_KEY=sk-...                      # only for hosted services (OpenRouter, OpenAI, ...)
Variable Required Description
JUDGMENT_BACKEND No systemone (default) or openai. Setting any JUDGMENT_* / TYPESAFE_* variable enables the tools.
JUDGMENT_BASE_URL No Default https://api.typesafe.ai for systemone, http://localhost:11434/v1 for openai. Alias: TYPESAFE_BASE_URL.
JUDGMENT_MODEL For openai Default jev-latest for systemone; required for openai (e.g. qwen3:8b). Alias: TYPESAFE_DEFAULT_MODEL. Aliases like jev-latest move with releases; pin a version after tuning thresholds.
JUDGMENT_API_KEY For hosted services Sent as Authorization: Bearer. Omit for local servers. Alias: TYPESAFE_API_KEY.
JUDGMENT_TIMEOUT No Per-request timeout in seconds (default 10 for systemone, 120 for openai). Retries on 408/429/5xx and transport errors follow the official TypeSafe SDK policy (2 retries, exponential backoff, Retry-After honoured). Alias: TYPESAFE_TIMEOUT.
JUDGMENT_SAMPLES No openai only, 1โ€“10 (default 1). Above 1, each question set is asked that many times at a sampling temperature and vote frequency becomes the probability. Multiplies cost and latency.
JUDGMENT_TIME_BUDGET No Seconds one tool call may spend on backend calls in total (default 300). Pairs or texts still pending at the deadline are skipped and listed in errors.

[!WARNING] With a hosted backend, data leaves your network. The projected fields of the scanned records โ€” names, model numbers, addresses, and supplier/company contact URLs, emails and phone numbers โ€” are sent to whatever JUDGMENT_BASE_URL points at. Self-host (Laya, Ollama, โ€ฆ) if that is not acceptable. Users are deliberately not supported by these tools because user records are personal data. For TypeSafe, review their legal terms (zero data retention is an enterprise option). In multi-identity mode, restrict who may call these tools with SNIPEIT_IDENTITY_<KEY>_ALLOWED_TOOLS.

Cost and limits. find_duplicates compares every pair when the table is small (โ‰ค max_pairs pairs) and otherwise pre-filters lexically similar pairs in code (capped at 20 000 comparisons), so backend calls are bounded by max_pairs (default 100, max 500). match_records sends at most candidates_per_text records (default 50, max 254) plus none per text. Both tools report usage token counts and elapsed_seconds, and stop submitting work when JUDGMENT_TIME_BUDGET runs out.

Reading the results. Every judgment carries a confidence (0โ€“1) and a confidence_band: high (โ‰ฅ 0.9) is safe to act on, medium (0.5โ€“0.9) should be confirmed by a person, low should not be acted on. Every result also says who judged: backend, model, calibrated and confidence_source (model for System One models, self_reported or vote_frequency for chat models). The bands are only meaningful when calibrated is true; with a chat backend treat them as a hint and keep a human in the loop. find_duplicates separates duplicates (judged the same), review (related, possibly the same) and different_count; treat review as a to-check list, never a to-merge list.

Production Deployment

For running the server as a long-lived HTTPS service on a Linux VM (the typical shape for OAuth mode), the repo ships two helper scripts under scripts/:

Script Purpose
scripts/setup-snipeit-mcp.sh One-shot installer. Creates a snipeit-mcp service user, installs uv if missing, writes /etc/snipeit-mcp.env (seeding SNIPEIT_* values from a .env at the repo root if present), installs and starts a hardened systemd unit, and probes the local OAuth metadata endpoint. Idempotent.
scripts/update-snipeit-mcp.sh Routine update โ€” git pull, re-uv sync, restart the service, re-probe.

Quick-start on a fresh VM (assumes Debian/Ubuntu with systemd; needs root):

# 1. Clone the source tree
sudo git clone https://github.com/jameshgordy/snipeit-mcp.git /opt/snipeit-mcp

# 2. (Optional) Drop a .env at the repo root so setup can seed
#    SNIPEIT_URL / SNIPEIT_OAUTH_CLIENT_ID / _SECRET / SNIPEIT_MCP_BASE_URL.
#    Missing values become __FILL_ME__ placeholders in /etc/snipeit-mcp.env.
scp .env you@vm:/tmp/snipeit-seed.env
sudo mv /tmp/snipeit-seed.env /opt/snipeit-mcp/.env

# 3. Install and start
sudo bash /opt/snipeit-mcp/scripts/setup-snipeit-mcp.sh

# 4. Future updates
sudo bash /opt/snipeit-mcp/scripts/update-snipeit-mcp.sh

[!NOTE] The scripts are committed with the executable bit set, so sudo /opt/snipeit-mcp/scripts/... works once they're checked out via git clone. The sudo bash ... form above is the bullet-proof alternative โ€” it doesn't care about file permissions, useful if you transferred the scripts via scp/drag-and-drop and the bit didn't come along.

What the installer configures:

Path Purpose
/opt/snipeit-mcp/ Source tree (owned by service user)
/var/lib/snipeit-mcp/ FASTMCP_HOME โ€” DCR'd MCP client registrations persist here
/etc/snipeit-mcp.env Secrets and deployment-specific URLs (SNIPEIT_* only)
/etc/systemd/system/snipeit-mcp.service systemd unit; infra settings (MCP_TRANSPORT, MCP_HOST, MCP_PORT, LOG_LEVEL, FASTMCP_HOME) are baked into its Environment= directives

Configurable at install time via environment variables on the setup-snipeit-mcp.sh invocation:

Variable Default Notes
SOURCE_DIR /opt/snipeit-mcp Source tree path
STATE_DIR /var/lib/snipeit-mcp Service-user home / FASTMCP_HOME
ENV_FILE /etc/snipeit-mcp.env Generated env file
SEED_ENV_FILE $SOURCE_DIR/.env Optional seed for SNIPEIT_* values
MCP_TRANSPORT http Always http for OAuth mode
MCP_HOST 127.0.0.1 Bind address. Loopback by default; set MCP_HOST=0.0.0.0 to expose on all interfaces (e.g. a reverse proxy on a different host)
MCP_PORT 8000 TCP port
LOG_LEVEL INFO

[!IMPORTANT] The scripts do not configure TLS โ€” the server listens on plain HTTP on the chosen MCP_PORT. For public OAuth use, terminate TLS in front of it (corporate reverse proxy, Caddy, nginx, โ€ฆ) with a trusted certificate for the hostname in SNIPEIT_MCP_BASE_URL.

Exposing a VPN-only Snipe-IT to web-based MCP clients (DMZ reverse proxy)

Web-based MCP clients (Claude.ai, Mistral's Le Chat, โ€ฆ) run their MCP transport through the client vendor's own backend, which needs to reach SNIPEIT_MCP_BASE_URL from the public internet โ€” a VPN-only address won't work. If your Snipe-IT instance itself is VPN-only, the typical shape is to keep the MCP VM internal and put a public-facing reverse proxy in a DMZ in front of it:

Web client backend โ”€โ”€HTTPSโ”€โ”€โ–บ public reverse proxy (DMZ) โ”€โ”€HTTPโ”€โ”€โ–บ MCP VM (internal) โ”€โ”€HTTPSโ”€โ”€โ–บ Snipe-IT (internal)

What the DMZ proxy needs:

  • Public hostname matching SNIPEIT_MCP_BASE_URL (e.g. snipeit.mcp.example.com).
  • Trusted TLS certificate for that hostname โ€” client backends will not accept internal CAs.
  • Upstream: the internal VM on http://<vm-ip>:<MCP_PORT>.
  • Forwarded headers: Host, X-Forwarded-Proto: https, X-Forwarded-Host, X-Forwarded-For. FastMCP uses these to build correct OAuth metadata URLs.
  • Do not strip WWW-Authenticate from upstream responses โ€” MCP clients (Inspector, mcp-remote, web clients) rely on it to discover the OAuth flow. Header-allowlist proxies are a common culprit.
  • Do not add CORS headers โ€” FastMCP handles its own.

[!NOTE] VPN is still required for the initial Snipe-IT login. The OAuth flow redirects the user's browser to https://<your-snipeit>/oauth/authorize for sign-in (and SSO bounce), which is VPN-only by definition. Once the user has signed in once, subsequent MCP tool calls and refresh-token rotation go client backend โ†’ DMZ โ†’ MCP VM โ†’ Snipe-IT entirely server-side, so users can keep using the web client from anywhere until the refresh token expires or is revoked, at which point a one-time VPN reconnect is needed to re-login.

MCP Client Configuration

The right configuration depends on whether the server runs in API-key mode (stdio, local, one shared identity) or OAuth mode (HTTP, remote, per-user identity). See the previous section for how the server picks between them.

Claude Desktop / Claude Code โ€” API-key mode (stdio)

Add to your MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Option A: Install directly from GitHub (no clone required)

{
  "mcpServers": {
    "snipeit": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jameshgordy/snipeit-mcp",
        "snipeit-mcp"
      ],
      "env": {
        "SNIPEIT_URL": "https://your-snipeit-instance.com",
        "SNIPEIT_TOKEN": "your-api-token-here"
      }
    }
  }
}

Option B: Run from a local clone

{
  "mcpServers": {
    "snipeit": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/snipeit-mcp",
        "run",
        "snipeit-mcp"
      ],
      "env": {
        "SNIPEIT_URL": "https://your-snipeit-instance.com",
        "SNIPEIT_TOKEN": "your-api-token-here"
      }
    }
  }
}

Claude Desktop / Claude Code โ€” OAuth mode (via mcp-remote)

When the server runs in OAuth mode it speaks HTTP, not stdio, so it cannot be launched directly by Claude Desktop. Use mcp-remote as a stdio bridge โ€” it handles Dynamic Client Registration, opens the browser for interactive login, caches the resulting tokens, and refreshes them transparently. The server must already be running and reachable at the URL below (e.g. on a VM, behind a reverse proxy, or on localhost for dev).

{
  "mcpServers": {
    "snipeit": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-mcp-public-url/mcp"
      ]
    }
  }
}

[!NOTE] No SNIPEIT_* env vars belong here โ€” the server holds them. The first connection opens a browser tab for Snipe-IT login (going through your SSO if configured); subsequent connections reuse the cached refresh token.

Claude.ai web (OAuth mode only)

Open https://claude.ai โ†’ Settings โ†’ Connectors โ†’ Add custom connector. Paste the public URL of your running MCP server (e.g. https://your-mcp-public-url/mcp) and follow the OAuth prompt.

[!IMPORTANT] Claude.ai web requires the MCP server to be reachable from the public internet over HTTPS โ€” localhost and unencrypted HTTP do not work here. Use the mcp-remote bridge instead if you only have a localhost deployment.

Cursor

Add to your Cursor MCP settings using the same JSON shape as the Claude Desktop examples above โ€” stdio (API-key) or mcp-remote bridge (OAuth) โ€” whichever matches your server mode.

MCP Inspector (debugging)

npx @modelcontextprotocol/inspector

Then in the Inspector UI:

  • Transport Type: Streamable HTTP
  • URL: your server's /mcp endpoint
  • Connection Type: must be Via Proxy, not Direct

[!NOTE] Why "Via Proxy"? The Inspector UI is a static frontend served at http://localhost:6274 and the MCP server lives at a different origin (e.g. http://localhost:8000). In Direct mode the browser tries to talk to the MCP server itself, which fails for two compounding reasons: (a) FastMCP doesn't emit CORS headers for the Inspector origin, so requests are blocked client-side, and (b) the OAuth redirect flow needs server-side state the browser-only client can't keep. Via Proxy routes traffic through Inspector's own backend (at localhost:6277), which is same-origin from the MCP server's perspective and handles OAuth state correctly.

[!WARNING] Leave Client ID and Client Secret in the OAuth panel empty โ€” Inspector will perform Dynamic Client Registration with the MCP server. Pasting your Snipe-IT (upstream) client_id and secret there is the most common misconfiguration; those credentials belong only in the server's .env, not in any MCP client.

Available Tools (40 core + 2 optional)

Asset Tools (8)

Tool Description
manage_assets CRUD operations with bytag/byserial lookup and advanced filtering
asset_operations State operations (checkout, checkin, audit, restore)
bulk_asset_operations Bulk edit and bulk audit across many assets at once (Snipe-IT v8.7+)
asset_files File attachments (upload, list, download, delete)
asset_labels Generate printable PDF labels
asset_maintenance Full maintenance lifecycle (create, list, get, update, delete, complete)
asset_licenses View licenses assigned to an asset
asset_requests Submit/cancel checkout requests, list own requests and requestable assets

Inventory Tools (5)

Tool Description
manage_consumables CRUD operations for consumables
manage_components CRUD operations for components
component_operations Checkout/checkin components to assets
manage_accessories CRUD operations for accessories
accessory_operations Checkout/checkin accessories to users, assets, or locations

Kit Tools (1)

Tool Description
manage_kits CRUD for predefined kits plus kit content management (models, licenses, accessories, consumables)

User & Organization Tools (6)

Tool Description
manage_users CRUD operations for users (+ restore, me)
user_assets Get items checked out to a user (assets, accessories, licenses, consumables, eulas)
user_two_factor Reset user two-factor authentication
manage_companies CRUD operations for companies
manage_departments CRUD operations for departments
manage_groups CRUD operations for permission groups

Configuration Tools (7)

Tool Description
manage_categories Manage categories for all item types
manage_manufacturers Manage manufacturer information
manage_models Manage asset models (+ list assets by model)
manage_status_labels Manage status labels (+ list assets by status)
manage_locations Manage locations (+ list assets/users by location)
manage_suppliers Manage supplier information
manage_depreciations Manage depreciation schedules

Custom Field Tools (2)

Tool Description
manage_fields CRUD + associate/disassociate fields with fieldsets
manage_fieldsets CRUD operations for fieldsets (+ field listing, reorder)

License Tools (3)

Tool Description
manage_licenses CRUD operations for licenses
license_seats Manage license seat assignments
license_files Manage license file attachments

Reporting & Audit Tools (3)

Tool Description
activity_reports Query activity logs and item history
status_summary Get asset counts grouped by status label
audit_tracking Track assets due/overdue for audit

Import Tools (1)

Tool Description
manage_imports CSV import workflow (upload, then process with type and column mapping)

Data Quality Tools (2, optional โ€” require a judgment backend)

Tool Description
find_duplicates Find likely duplicate manufacturers, models, suppliers, locations, categories, companies or departments; pairwise judgments with score, confidence, both records and a merge hint
match_records Resolve free-text names to existing record ids (or none) with per-option probabilities โ€” for import prep and natural-language asset creation

System Administration Tools (4)

Tool Description
system_info Get Snipe-IT version information
manage_backups List and download database backups
ldap_operations LDAP sync and connection testing
model_files Manage file attachments for asset models

Usage Examples

Create an Asset

{
  "action": "create",
  "asset_data": {
    "status_id": 1,
    "model_id": 5,
    "asset_tag": "LAP-001",
    "name": "MacBook Pro 14",
    "serial": "C02X12345"
  }
}

Create a User

{
  "action": "create",
  "user_data": {
    "first_name": "John",
    "last_name": "Doe",
    "username": "jdoe",
    "email": "jdoe@example.com",
    "password": "securepassword",
    "password_confirmation": "securepassword",
    "department_id": 1
  }
}

Get Items Checked Out to User

{
  "user_id": 123,
  "asset_type": "all"
}

Checkout Component to Asset

{
  "action": "checkout",
  "component_id": 45,
  "checkout_data": {
    "assigned_to": 123,
    "assigned_qty": 2,
    "note": "RAM upgrade"
  }
}

Query Activity Logs

{
  "action": "list",
  "action_type": "checkout",
  "limit": 50
}

Create Custom Field

{
  "action": "create",
  "field_data": {
    "name": "MAC Address",
    "element": "text",
    "format": "MAC"
  }
}

Associate Field with Fieldset

{
  "action": "associate",
  "field_id": 5,
  "fieldset_id": 1,
  "required": true,
  "order": 1
}

Response Format

All tools return structured JSON responses:

Success (create):

{
  "success": true,
  "action": "create",
  "asset": {
    "id": 123,
    "asset_tag": "LAP-001",
    "name": "MacBook Pro 14"
  }
}

Success (list):

All list endpoints return pagination metadata:

{
  "success": true,
  "action": "list",
  "count": 3,
  "total": 1602,
  "limit": 20,
  "offset": 0,
  "has_more": true,
  "assets": [ ... ]
}
Field Description
count Number of items in this page
total Total items matching the query
limit Page size used
offset Starting offset
has_more true if more pages remain

Error:

{
  "success": false,
  "error": "Asset not found: Asset with tag LAP-999 not found."
}

Architecture

src/mcp_server_snipeit/
โ”œโ”€โ”€ __init__.py        # Public API re-exports
โ”œโ”€โ”€ __main__.py        # Entry point (snipeit-mcp script)
โ”œโ”€โ”€ mcp_server.py      # FastMCP instance + tool whitelist + optional-tool visibility
โ”œโ”€โ”€ client.py          # SnipeIT API clients
โ”œโ”€โ”€ judgment.py        # Judgment backend config/selection + shared HTTP retry (optional tools)
โ”œโ”€โ”€ systemone.py       # System One protocol backend (TypeSafe Jev, Laya, CLM, โ€ฆ)
โ”œโ”€โ”€ chat_judge.py      # OpenAI-compatible chat backend (Ollama, vLLM, LM Studio, โ€ฆ)
โ”œโ”€โ”€ config.py          # Transport + auth-mode config (OAuth / API key / multi-identity)
โ”œโ”€โ”€ identity.py        # Multi-identity registry (tokens โ†’ PATs), ContextVar, validation
โ”œโ”€โ”€ http_auth.py       # Multi-identity HTTP auth (401, /healthz) + audit log + tool policy
โ”œโ”€โ”€ schemas.py         # Pydantic input schemas
โ””โ”€โ”€ tools/             # 11 modules grouped by Snipe-IT domain
    โ”œโ”€โ”€ assets.py
    โ”œโ”€โ”€ inventory.py
    โ”œโ”€โ”€ foundational.py
    โ”œโ”€โ”€ licenses.py
    โ”œโ”€โ”€ people.py
    โ”œโ”€โ”€ custom_fields.py
    โ”œโ”€โ”€ reports.py
    โ”œโ”€โ”€ imports.py
    โ”œโ”€โ”€ system.py
    โ””โ”€โ”€ data_quality.py   # find_duplicates / match_records (judgment-backed)

Built with:

  • FastMCP: Python framework for MCP servers
  • snipeit-python-api: Snipe-IT API client
  • Pydantic: Data validation and type safety
  • Judgment backends (optional): the System One protocol (TypeSafe Jev, Laya, CLM, โ€ฆ) or any OpenAI-compatible chat server (Ollama, โ€ฆ) behind the data-quality tools

Troubleshooting

Authentication Errors

  • Verify your Snipe-IT URL includes the protocol (https://)
  • Check that your API token is valid and not expired
  • Ensure the token has appropriate permissions for the operations

Connection Errors

  • Verify network connectivity to your Snipe-IT instance
  • Check for any firewall or proxy restrictions
  • Ensure the Snipe-IT instance is running

Validation Errors

  • Check that required fields are provided (e.g., status_id and model_id for assets)
  • Verify that referenced IDs exist (categories, models, locations, etc.)
  • Review the tool documentation for required parameters

License

MIT License. See LICENSE.

Contributing

Contributions welcome! Please open an issue or submit a pull request.

Issues and pull requests are generally reviewed on Mondays (unless I'm on vacation), so expect a reply within about a week. New issues get labelled automatically in the meantime.

Package "mcp-server-snipeit" not found

This package may not be indexed in our database yet. Please try again later or check the package repository directly.

Browse Repository