MCP 服务器

snipeit-mcp

Read-only MCP server for Snipe-IT v7 REST API, providing search and retrieval of assets, users, models, categories, and locations without modification.

README

🔧 Snipe-IT MCP

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

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

🚀 最初にお読みください

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

段階	やること	対象の手順
① 共通準備	PythonとAPIトークンを準備する	手順1〜5
② アプリを選ぶ	CodexまたはClaudeへ登録する	手順6
③ 使ってみる	資産やライセンスを操作する	手順7〜9

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

🧑‍💻 コマンドを入力する場所は、macOSの「ターミナル」アプリです。コードブロック右上のコピーボタンを使うと入力ミスを減らせます。

📖 このREADMEに出てくる言葉

言葉	かんたんな意味
MCP	CodexやClaudeと、外部サービスをつなぐ仕組み
APIトークン	Snipe-ITへ安全に接続するための長いパスワード
ターミナル	Macへ文字で命令を入力するアプリ
Python仮想環境	このプログラム専用のPython実行場所
リポジトリ	このプログラム一式が入っているフォルダ

✨ できること

Snipe-IT APIへの接続確認
資産の一覧、検索、詳細取得、登録
ライセンスの一覧、検索、詳細取得、登録
ライセンスシートの一覧、資産への自動・明示割り当てと解除
ユーザーの一覧、検索、詳細取得
資産モデル、カテゴリ、ロケーションの一覧と検索

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

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

次のものが必要です。

Python 3.11以上
Codex CLIまたはClaude Code / Claude Desktop
接続可能なSnipe-IT v7サーバー
Snipe-ITのPersonal Access Token
資産やライセンスを登録・割り当てする場合は、対応する書き込み権限

ターミナルを開き、次のコマンドを1行ずつ実行します。

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

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

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

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

Snipe-ITへログインします。
画面右上のアカウントメニューを開きます。
Manage API Keys を選びます。
Create New Token を選び、用途が分かる名前を付けて作成します。
表示されたトークンを一時的に安全な場所へコピーします。

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

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

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

ターミナルで、このプログラムが入っているフォルダへ移動します。次の場所へ配置した場合は、そのままコピーして実行できます。

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

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

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

プロジェクトを確認できました と表示されれば成功です。何も表示されない場合は、cd のフォルダ指定を確認してください。

4. 🐍 Python環境を準備する

手順3から続けて、次の3行を1行ずつ実行します。処理に数分かかることがあります。

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

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

.venv/bin/pytest

最後に 14 passed のように表示されれば成功です。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は安全のため起動しません。

6. 🤖 CodexまたはClaudeを選ぶ

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

使いたいアプリ	進む場所
Codex	「🅰️ Codex」を実施
Claude Code	「🅱️ Claude」→「B-1」を実施
Claude Desktop	「🅱️ Claude」→「B-2」を確認
CodexとClaudeの両方	AとBの両方を実施

🅰️ 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 \
  -- \
  "$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 \
  -- \
  "$SNIPEIT_MCP_DIR/.venv/bin/snipeit-mcp"

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

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

codex mcp list

一覧に snipeit が表示され、コマンドの末尾が .venv/bin/snipeit-mcp になっていることを確認します。

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

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

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

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

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

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

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

🅱️ Claude

このMCPは標準のstdioトランスポートを使用しているため、Pythonコードを変更せずClaudeでも利用できます。Claude CodeまたはClaude Desktopのうち、利用する方へ進んでください。

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 \
  --transport stdio \
  --scope user \
  snipeit -- \
  "$SNIPEIT_MCP_DIR/.venv/bin/snipeit-mcp"

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

登録状態を確認します。

claude mcp list
claude mcp get snipeit

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

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

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

B-2. 🖥️ Claude Desktopへ登録する

Claude Desktopでは、ローカルMCPをDesktop Extension（DXT）としてインストールできます。

Claude Desktopの Settings → Extensions を開きます。
Advanced settings → Extension Developer を開きます。
DXTパッケージを選択してインストールします。
Snipe-IT URLとAPIトークンファイルを設定します。
Claude Desktopを再起動して、新しい会話で接続確認を依頼します。

⚠️ 初心者の方にはClaude Codeをおすすめします。 現時点のリポジトリには、Claude Desktopへ直接インストールするDXTファイルが含まれていません。Claude Desktopで利用するには、manifest.json を追加してDXTパッケージ化する作業が必要です。

ローカル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になることがあります。自動割り当てツールはこの違いを内部で処理します。

⚙️ 設定を変更する

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

Codexの場合:

codex mcp remove snipeit

Claude Codeの場合:

claude mcp remove snipeit

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

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"

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

`SNIPEIT_URL is required`

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

`SNIPEIT_API_TOKEN or SNIPEIT_API_TOKEN_FILE is required`

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

`SNIPEIT_API_TOKEN_FILE cannot be read`

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

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

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

codex mcp list
claude mcp list

`SNIPEIT_API_TOKEN_FILE permissions must be 600`

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

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

`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

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

APIトークンをGitへコミットしないでください。
APIトークンをAIクライアントのプロンプトへ貼り付けないでください。
.env やトークンファイルをこのリポジトリへ置かないでください。
トークンには必要最小限の権限だけを付与してください。
不要になったトークンはSnipe-IT側で失効させてください。

📜 ライセンス

MIT