🔧 Snipe-IT MCP

CodexやClaudeに日本語でお願いするだけで、Snipe-ITの資産やライセンスを確認・登録できるようにするプログラムです。

たとえば「未使用のPCを一覧にして」「このライセンスを資産へ割り当てて」のように操作できます。

🚀 最初にお読みください

セットアップは、大きく分けて次の3段階です。上から順番に進めれば大丈夫です。

💡 CodexとClaudeの両方を設定する必要はありません。 手順6で、普段使う方だけを選んでください。

🧑‍💻 macOS・Linuxではターミナル（Bash/Zsh）、WindowsではPowerShellを使います。OS別のコードブロックから該当するものを実行してください。

このREADMEはmacOS、Red Hat Enterprise Linuxを含む一般的なLinux（Bash/Zsh）、Windows PowerShellの手順を掲載しています。LinuxではPython 3.11以上が利用できれば、ディストリビューション固有の違いは主にPythonのインストール方法だけです。

📖 このREADMEに出てくる言葉

Related MCP server: invgate-mcp

✨ できること

• Snipe-IT APIへの接続確認

• 資産の一覧、検索、詳細取得、登録

• ライセンスの一覧、検索、詳細取得、登録

• ライセンスシートの一覧、資産への自動・明示割り当てと解除

• ユーザーの一覧、検索、詳細取得

• 資産モデル、カテゴリ、ロケーションの一覧と検索

ℹ️ 既存データの更新・削除には対応していません。

各一覧ツールは、limitに100を超える件数を指定できます。limitを省略すると25件、limit=nullを指定すると全件を内部でページングして取得します。ライセンスシート一覧は常に全件取得します。取得予定が500件を超える場合、MCPは一覧を返す前に警告し、AIへ利用者の明示的な確認を求めます。同意後にAIがconfirm_large_result=trueで再実行すると取得されます。警告の閾値はSNIPEIT_LARGE_RESULT_THRESHOLD環境変数で変更できます。

1. ✅ 必要なものを確認する

次のものが必要です。

• Python 3.11以上（Windowsではインストール時にPATHへ追加）

• Codex CLIまたはClaude Code（Claude Desktopは別途DXTパッケージ化が必要）

• 接続可能なSnipe-IT v7サーバー

• Snipe-ITのPersonal Access Token

• 資産やライセンスを登録・割り当てする場合は、対応する書き込み権限

macOS・Linuxではターミナルを開き、次のコマンドを実行します。

python3 --version
codex --version
claude --version

WindowsではPowerShellを開き、次を実行します。

python --version
codex --version
claude --version

💡 codex --version と claude --version は、利用する方だけ成功すれば問題ありません。使わない方でエラーが出ても無視できます。

python3 --version の結果が Python 3.11 以上なら準備完了です。3.10以下の場合は、先にPython 3.11以上をインストールしてください。

2. 🔑 Snipe-ITでAPIトークンを作成する

1. Snipe-ITへログインします。

2. 画面右上のアカウントメニューを開きます。

3. Manage API Keys を選びます。

4. Create New Token を選び、用途が分かる名前を付けて作成します。

5. 表示されたトークンを一時的に安全な場所へコピーします。

⚠️ 重要: トークンは再表示できない場合があります。ただし、チャット、ソースコード、.env、Gitの履歴には貼り付けないでください。次の手順5で安全なファイルへ保存します。

APIトークンの権限は、トークンを作成したSnipe-ITユーザーの権限を引き継ぎます。参照だけなら閲覧権限、資産・ライセンスの登録や割り当てには、それぞれを操作できる権限が必要です。必要以上に強い権限を与えず、専用ユーザーを用意することを推奨します。

3. 📁 プロジェクトのフォルダへ移動する

このプログラムが入っているフォルダへ移動します。以下は配置場所の例です。

macOS・Linux（Bash/Zsh）:

cd "$HOME/Tech/CodeXWorkSpace/snipeit-mcp"

Windows（PowerShell）:

Set-Location "$HOME\Tech\CodeXWorkSpace\snipeit-mcp"

READMEとPythonプロジェクトが見えることを確認します。

test -f pyproject.toml && echo "プロジェクトを確認できました"

PowerShellでは次を実行します。

Test-Path pyproject.toml

macOS・Linuxでプロジェクトを確認できました、PowerShellでTrueと表示されれば成功です。そうでない場合は、移動先を確認してください。

4. 🐍 Python環境を準備する

手順3から続けて実行します。処理に数分かかることがあります。

macOS・Linux（Bash/Zsh）:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e '.[dev]'

Windows（PowerShell）:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

インストール後、テストを実行します。

.venv/bin/pytest

PowerShellでは次を実行します。

.\.venv\Scripts\pytest.exe

最後に passed と表示され、failed がなければ成功です。failed が表示された場合は、先へ進まず「🆘 トラブルシューティング」を確認してください。

5. 🔐 APIトークンを安全に保存する

このMCPは、APIトークンを環境変数へ直接書く代わりに、利用者だけが読めるファイルから読み込めます。

実行途中で Snipe-IT API token: と表示されます。手順2で作成したトークンを貼り付け、Enterを押してください。

🙈 入力中は、セキュリティのため文字も * も表示されません。画面が動かなくても入力されています。

mkdir -p "$HOME/.config/snipeit-mcp"
chmod 700 "$HOME/.config/snipeit-mcp"
printf 'Snipe-IT API token: '
read -r -s SNIPEIT_TOKEN
printf '\n'
printf '%s\n' "$SNIPEIT_TOKEN" > "$HOME/.config/snipeit-mcp/token"
unset SNIPEIT_TOKEN
chmod 600 "$HOME/.config/snipeit-mcp/token"

ファイルの権限が 600 であることを確認します。

ls -l "$HOME/.config/snipeit-mcp/token"

表示の先頭が -rw------- なら成功です。それ以外の場合、このMCPは安全のため起動しません。

Windows（PowerShell）では、次を実行します。WindowsではchmodではなくACLで、現在の利用者だけがトークンファイルを読めるようにします。

$TokenDir = Join-Path $HOME ".config\snipeit-mcp"
$TokenFile = Join-Path $TokenDir "token"
New-Item -ItemType Directory -Force -Path $TokenDir | Out-Null
$SecureToken = Read-Host "Snipe-IT API token" -AsSecureString
$PlainToken = [System.Net.NetworkCredential]::new("", $SecureToken).Password
[System.IO.File]::WriteAllText($TokenFile, $PlainToken)
$PlainToken = $null
$SecureToken.Dispose()
icacls $TokenFile /inheritance:r /grant:r "${env:USERNAME}:(R)"

Successfully processed 1 filesと表示されれば保存完了です。WindowsではPythonからACLの安全性を判定できないため、上のicaclsを省略しないでください。

6. 🤖 CodexまたはClaudeを選ぶ

普段使うアプリに合う方だけを選んでください。

🅰️ Codex

A-1. 🔗 MCPサーバーを登録する

まず、このリポジトリの絶対パスを変数へ保存します。

SNIPEIT_MCP_DIR="$(pwd -P)"

次のコマンド内にある http://192.168.186.128 だけを、自分のSnipe-ITのURLへ置き換えて実行します。URLの末尾に /api/v1 は付けません。

codex mcp add snipeit \
  --env SNIPEIT_URL=http://192.168.186.128 \
  --env SNIPEIT_API_TOKEN_FILE="$HOME/.config/snipeit-mcp/token" \
  --env SNIPEIT_TIMEOUT=20 \
  --env SNIPEIT_LARGE_RESULT_THRESHOLD=500 \
  -- \
  "$SNIPEIT_MCP_DIR/.venv/bin/snipeit-mcp"

HTTPSで公開している場合の例は次のとおりです。

codex mcp add snipeit \
  --env SNIPEIT_URL=https://snipeit.example.com \
  --env SNIPEIT_API_TOKEN_FILE="$HOME/.config/snipeit-mcp/token" \
  --env SNIPEIT_TIMEOUT=20 \
  --env SNIPEIT_LARGE_RESULT_THRESHOLD=500 \
  -- \
  "$SNIPEIT_MCP_DIR/.venv/bin/snipeit-mcp"

⚠️ HTTP版とHTTPS版は、どちらか一方だけを実行してください。

Windows（PowerShell）では次を実行します。URLは自分の環境に置き換えてください。

$SnipeItMcpDir = (Resolve-Path ".").Path
$SnipeItTokenFile = Join-Path $HOME ".config\snipeit-mcp\token"
codex mcp add snipeit `
  --env "SNIPEIT_URL=https://snipeit.example.com" `
  --env "SNIPEIT_API_TOKEN_FILE=$SnipeItTokenFile" `
  --env "SNIPEIT_TIMEOUT=20" `
  --env "SNIPEIT_LARGE_RESULT_THRESHOLD=500" `
  -- `
  "$SnipeItMcpDir\.venv\Scripts\snipeit-mcp.exe"

A-2. 🔍 登録状態を確認する

codex mcp list

一覧にsnipeitが表示されることを確認します。macOS・Linuxではコマンド末尾が.venv/bin/snipeit-mcp、Windowsでは.venv\Scripts\snipeit-mcp.exeになります。

A-3. 🎉 Codexを再起動して接続確認する

MCPツールの一覧は、すでに開いているCodexセッションへ自動では追加されません。CodexアプリまたはCodex CLIを終了して起動し直し、新しいタスクを開いてください。

新しいタスクで、次のように依頼します。

Snipe-IT MCPの接続を確認して。

続けて、読み取り確認を行います。

Snipe-IT MCPを使って資産を10件取得して。

接続結果と資産一覧が返れば、Codexのセットアップは完了です。🎉

🅱️ Claude

このMCPは標準のstdioトランスポートを使用しているため、Pythonコードを変更せずClaude Codeで利用できます。Claude DesktopについてはB-2の制約を確認してください。

B-1. 💻 Claude Codeへ登録する

プロジェクト直下で、絶対パスを変数へ保存します。

SNIPEIT_MCP_DIR="$(pwd -P)"

次のコマンド内にある http://192.168.186.128 だけを、自分のSnipe-ITのURLへ置き換えて実行します。--scope user により、すべてのClaude Codeプロジェクトから利用できます。

claude mcp add \
  --env SNIPEIT_URL=http://192.168.186.128 \
  --env SNIPEIT_API_TOKEN_FILE="$HOME/.config/snipeit-mcp/token" \
  --env SNIPEIT_TIMEOUT=20 \
  --env SNIPEIT_LARGE_RESULT_THRESHOLD=500 \
  --transport stdio \
  --scope user \
  snipeit -- \
  "$SNIPEIT_MCP_DIR/.venv/bin/snipeit-mcp"

HTTPSで公開している場合は、SNIPEIT_URL を https://snipeit.example.com のように変更します。URL末尾に /api/v1 は付けません。

Windows（PowerShell）では次を実行します。URLは自分の環境に置き換えてください。

$SnipeItMcpDir = (Resolve-Path ".").Path
$SnipeItTokenFile = Join-Path $HOME ".config\snipeit-mcp\token"
claude mcp add `
  --env "SNIPEIT_URL=https://snipeit.example.com" `
  --env "SNIPEIT_API_TOKEN_FILE=$SnipeItTokenFile" `
  --env "SNIPEIT_TIMEOUT=20" `
  --env "SNIPEIT_LARGE_RESULT_THRESHOLD=500" `
  --transport stdio `
  --scope user `
  snipeit -- `
  "$SnipeItMcpDir\.venv\Scripts\snipeit-mcp.exe"

登録状態を確認します。

claude mcp list
claude mcp get snipeit

Claude Codeを起動し、/mcp でも接続状態を確認できます。新しい会話で次のように依頼してください。

Snipe-IT MCPの接続を確認して。

接続結果が返れば、Claude Codeのセットアップは完了です。🎉

B-2. 🖥️ Claude Desktopについて

現時点のリポジトリには、Claude Desktopへ直接インストールできるDXTパッケージやmanifest.jsonが含まれていません。そのため、このREADMEだけではClaude Desktopへの登録を完了できません。現在サポートしている手順はCodexとClaude Codeです。

Claude Desktopで利用する場合は、別途DXTパッケージ化が必要です。パッケージを用意した後、Claude Desktopの Settings → Extensions からインストールしてください。

ローカルMCPとPython製DXTはClaude Desktopでサポートされています。詳細はAnthropicのローカルMCP公式手順を参照してください。

Claude CodeのMCPコマンドとスコープについてはClaude Code MCP公式ドキュメントを参照してください。

7. 💻 資産を登録する

資産登録には、少なくとも次の値が必要です。

• asset_tag: Snipe-IT内で一意の資産タグ

• model_id: 登録済み資産モデルのID

• status_id: 登録済みステータスラベルのID

まずモデルを確認します。

Snipe-ITの資産モデルを一覧表示して。

ステータスIDはSnipe-IT管理画面で確認し、次のように登録を依頼します。

Snipe-ITに次の資産を登録して。
asset_tag: PC-001
model_id: 3
status_id: 2
name: 営業用ノートPC
serial: ABC123456

利用できる任意項目は name、serial、purchase_date、purchase_cost、notes、location_id です。日付は YYYY-MM-DD 形式で指定してください。

8. 📄 ライセンスを登録する

ライセンス登録には、少なくとも次の値が必要です。

• name: ライセンス名

• seats: 購入したシート数

• category_id: ライセンス用カテゴリのID

カテゴリを確認してから登録します。

Snipe-ITのカテゴリを一覧表示して。

Snipe-ITに次のライセンスを登録して。
name: Example Software Business
seats: 10
category_id: 4
serial: XXXXX-XXXXX-XXXXX
expiration_date: 2027-03-31

利用できる任意項目は serial、purchase_date、purchase_cost、expiration_date、notes、manufacturer_id です。

9. 🔗 ライセンスを資産へ割り当てる

Snipe-ITでは、ライセンスそのものではなく、ライセンス内の個別シートを資産へ割り当てます。通常は、空いている中で最も小さいSeat番号をMCPが自動選択するツールを使用してください。

Snipe-ITで、ライセンスID 5の最も小さい番号の空きシートを資産ID 8へ割り当てて。
メモは「営業用PCへ割り当て」。

自動割り当ては全ページのシートを取得し、ライセンス内のSeat番号順に空席を選びます。同一MCPプロセス内ではライセンス単位で処理を直列化し、同時実行による同じ空席の選択を防ぎます。

💡 通常は上の自動割り当てを使ってください。空いている中で最も小さいSeat番号が自動で選ばれます。

Seat IDを自分で指定する方法は上級者向けです。明示指定には次の3つのIDが必要です。

• license_id: ライセンスID

• seat_id: ライセンス内のシートID

• asset_id: 割り当て先の資産ID

Seat IDを明示する場合は、まずライセンス、シート、資産を確認します。

Snipe-ITのライセンスを一覧表示して。

ライセンスID 5の空きシートをSeat番号順で取得して。

資産タグ PC-001を検索して、資産IDを確認して。

IDを確認できたら割り当てます。

Snipe-ITで、ライセンスID 5のシートID 12を資産ID 8へ割り当てて。
メモは「営業用PCへ割り当て」。

割り当て解除は次のように依頼します。

Snipe-ITで、ライセンスID 5のシートID 12の割り当てを解除して。

Snipe-ITのAPIで指定するSeat IDは全ライセンスを通じた一意なIDで、画面上のSeat番号とは異なる場合があります。たとえば、画面上のSeat 1がAPIではSeat ID 101になることがあります。自動割り当てツールはこの違いを内部で処理します。

⚙️ 設定を変更する

このMCPは.envを自動では読み込みません。実際の値は手順6のMCP登録コマンドで環境変数として渡します。利用できる設定項目は次の表のとおりです。

セキュリティ上、トークンの直接指定よりSNIPEIT_API_TOKEN_FILEを推奨します。

Snipe-ITのURLやプロジェクトの場所を変更した場合は、利用しているクライアントから一度登録を削除して再登録します。

Codexの場合:

codex mcp remove snipeit

Claude Codeの場合:

claude mcp remove snipeit

その後、「6. CodexまたはClaudeを選ぶ」から該当する登録手順を新しい値で再実行し、利用しているクライアントを再起動してください。

APIトークンだけを更新する場合は、登録し直す必要はありません。「5. APIトークンを安全なファイルへ保存する」を新しいトークンで再実行し、利用しているクライアントを再起動してください。

🗑️ アンインストール

利用しているクライアントから登録を削除します。

Codexの場合:

codex mcp remove snipeit

Claude Codeの場合:

claude mcp remove snipeit

Claude Desktopの場合は、Settings → Extensions から対象のExtensionをアンインストールします。

不要になったトークンはSnipe-ITの Manage API Keys から失効させてください。その後、ローカルのトークンファイルを削除できます。

rm "$HOME/.config/snipeit-mcp/token"

PowerShellでは次を実行します。

Remove-Item (Join-Path $HOME ".config\snipeit-mcp\token")

🆘 トラブルシューティング

SNIPEIT_URL is required

利用しているクライアントのMCP登録に SNIPEIT_URL が含まれていません。「設定を変更する」の手順で削除し、URLを指定して再登録してください。

SNIPEIT_API_TOKEN or SNIPEIT_API_TOKEN_FILE is required

トークンファイルの指定が登録されていません。「5. APIトークンを安全に保存する」と「6. CodexまたはClaudeを選ぶ」の該当手順を確認してください。

SNIPEIT_API_TOKEN_FILE cannot be read

ファイルが存在するか、登録時に絶対パスが保存されているか確認します。

ls -l "$HOME/.config/snipeit-mcp/token"

PowerShellでは次を実行します。

Test-Path (Join-Path $HOME ".config\snipeit-mcp\token")

利用しているクライアントに応じて登録状態を確認します。

codex mcp list
claude mcp list

SNIPEIT_API_TOKEN_FILE permissions must be 600（macOS・Linux）

トークンファイルの権限を修正します。

chmod 600 "$HOME/.config/snipeit-mcp/token"

WindowsではACLを設定し直します。

$TokenFile = Join-Path $HOME ".config\snipeit-mcp\token"
icacls $TokenFile /inheritance:r /grant:r "${env:USERNAME}:(R)"

Snipe-IT API returned HTTP 401

トークンが間違っている、失効している、または対象操作の権限がありません。Snipe-ITでトークンと、そのトークンを作成したユーザーの権限を確認してください。

Could not connect to the Snipe-IT API

URL、ネットワーク、VPN、DNS、ファイアウォールを確認します。SNIPEIT_URL にはブラウザでSnipe-ITを開く際のベースURLを指定し、/api/v1 は付けません。

MCPを変更したのに新しいツールが見えない

このプロジェクトは編集可能モードでインストールされるため、通常は再インストール不要です。ただし、起動中のMCPプロセスは古いコードを保持しています。Codex、Claude Code、Claude Desktopのうち利用しているクライアントを終了して起動し直し、新しい会話を開いてください。

🧪 開発者向けテスト

cd "$HOME/Tech/CodeXWorkSpace/snipeit-mcp"
.venv/bin/pytest

Windows（PowerShell）:

Set-Location "$HOME\Tech\CodeXWorkSpace\snipeit-mcp"
.\.venv\Scripts\pytest.exe

🛡️ セキュリティ上の注意

• APIトークンをGitへコミットしないでください。

• APIトークンをAIクライアントのプロンプトへ貼り付けないでください。

• .envやトークンファイルをこのリポジトリへ置かないでください。

• トークンには必要最小限の権限だけを付与してください。

• 不要になったトークンはSnipe-IT側で失効させてください。

📜 ライセンス

MIT