# 🔧 Snipe-IT MCP

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

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

## 🚀 最初にお読みください

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

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

> 💡 **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に出てくる言葉

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

## ✨ できること

- 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ではターミナルを開き、次のコマンドを実行します。

```bash
python3 --version
codex --version
claude --version
```

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

```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）:

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

Windows（PowerShell）:

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

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

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

PowerShellでは次を実行します。

```powershell
Test-Path pyproject.toml
```

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

## 4. 🐍 Python環境を準備する

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

macOS・Linux（Bash/Zsh）:

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

Windows（PowerShell）:

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

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

```bash
.venv/bin/pytest
```

PowerShellでは次を実行します。

```powershell
.\.venv\Scripts\pytest.exe
```

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

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

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

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

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

```bash
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` であることを確認します。

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

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

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

```powershell
$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 | 「🅰️ Codex」を実施 |
| Claude Code | 「🅱️ Claude」→「B-1」を実施 |
| Claude Desktop | 「🅱️ Claude」→「B-2」で現在の制約を確認 |
| CodexとClaudeの両方 | AとBの両方を実施 |

### 🅰️ Codex

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

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

```bash
SNIPEIT_MCP_DIR="$(pwd -P)"
```

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

```bash
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で公開している場合の例は次のとおりです。

```bash
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は自分の環境に置き換えてください。

```powershell
$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. 🔍 登録状態を確認する

```bash
codex mcp list
```

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

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

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

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

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

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

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

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

### 🅱️ Claude

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

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

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

```bash
SNIPEIT_MCP_DIR="$(pwd -P)"
```

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

```bash
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は自分の環境に置き換えてください。

```powershell
$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"
```

登録状態を確認します。

```bash
claude mcp list
claude mcp get snipeit
```

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

```text
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公式手順](https://support.anthropic.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)を参照してください。

Claude CodeのMCPコマンドとスコープについては[Claude Code MCP公式ドキュメント](https://code.claude.com/docs/en/mcp)を参照してください。

## 7. 💻 資産を登録する

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

- `asset_tag`: Snipe-IT内で一意の資産タグ
- `model_id`: 登録済み資産モデルのID
- `status_id`: 登録済みステータスラベルのID

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

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

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

```text
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

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

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

```text
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が自動選択するツールを使用してください。

```text
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を明示する場合は、まずライセンス、シート、資産を確認します。

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

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

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

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

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

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

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

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

## ⚙️ 設定を変更する

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

| 環境変数 | 必須 | 内容 | 既定値 |
|---|---|---|---|
| `SNIPEIT_URL` | 必須 | Snipe-ITのベースURL | なし |
| `SNIPEIT_API_TOKEN_FILE` | どちらか必須 | 権限600のトークンファイル | なし |
| `SNIPEIT_API_TOKEN` | どちらか必須 | トークンを直接指定 | なし |
| `SNIPEIT_TIMEOUT` | 任意 | APIリクエストのタイムアウト秒数 | `20` |
| `SNIPEIT_LARGE_RESULT_THRESHOLD` | 任意 | 大量取得前に確認を求める件数 | `500` |

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

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

Codexの場合:

```bash
codex mcp remove snipeit
```

Claude Codeの場合:

```bash
claude mcp remove snipeit
```

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

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

## 🗑️ アンインストール

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

Codexの場合:

```bash
codex mcp remove snipeit
```

Claude Codeの場合:

```bash
claude mcp remove snipeit
```

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

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

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

PowerShellでは次を実行します。

```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`

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

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

PowerShellでは次を実行します。

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

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

```bash
codex mcp list
claude mcp list
```

### `SNIPEIT_API_TOKEN_FILE permissions must be 600`（macOS・Linux）

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

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

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

```powershell
$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のうち利用しているクライアントを終了して起動し直し、新しい会話を開いてください。

## 🧪 開発者向けテスト

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

Windows（PowerShell）:

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

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

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

## 📜 ライセンス

MIT