Snipe-IT MCP Server

Snipe-IT MCP 服务器

A. 模型上下文协议（MCP） 用于管理的服务器 Snipe-IT（注：这是一个专有名词，通常指的是一种用于资产管理的软件或系统名称，在中文中直接保留原名，不进行翻译） 库存系统。此服务器为AI助手提供工具，以便在您的Snipe-IT实例中对资产和消耗品执行创建、读取、更新和删除（CRUD）操作。

特点/功能

• 综合资产管理创建、读取、更新、删除和搜索资产
• 资产运营资产的出库、入库、审计和恢复
• 文件管理上传、下载、列出和删除资产附件
• 标签生成为资产生成可打印的PDF标签
• 维护跟踪为资产创建维护记录
• 许可证管理查看与资产相关的许可证
• 耗材管理消耗品的完整CRUD（创建、读取、更新、删除）操作
• 类型安全使用 Pydantic 模型构建，以实现强大的验证功能
• 错误处理全面的错误处理和日志记录

要求

• Python 3.11 或更高版本
• 紫外线 包管理器
• 一个可运行的Snipe-IT实例，具有API访问权限
• Snipe-IT API令牌，需具备相应权限

安装

1. 克隆或下载此仓库

git clone 
cd snipeit-mcp

2. 使用UV安装依赖项

# Install dependencies and create virtual environment
uv sync

# This will:
# - Create a virtual environment at .venv
# - Install fastmcp, requests, and snipeit-python-api
# - Set up the project for development

注： 你第一次跑步 uv sync它将从本地路径安装 snipeit-python-api，路径为 /Users/work/Documents/Projects/Inventory/snipeit-python-api确保该目录存在。

或者，如果您想手动设置：

# Create virtual environment
uv venv --python 3.11

# Install dependencies
uv pip install fastmcp requests /Users/work/Documents/Projects/Inventory/snipeit-python-api

3. 配置环境变量

创建一个 .env 保存或导出这些环境变量：

export SNIPEIT_URL="https://your-snipeit-instance.com"
export SNIPEIT_TOKEN="your-api-token-here"

或者创建一个 .env 文件：

SNIPEIT_URL=https://your-snipeit-instance.com
SNIPEIT_TOKEN=your-api-token-here

要获取Snipe-IT API令牌：

1. 登录到您的Snipe-IT实例
2. 前往您的用户资料（点击右上角的您的名字）
3. 导航至“API令牌”或“个人访问令牌”
4. 生成一个具有适当权限的新令牌

使用方法

运行服务器

方法1：直接执行Python

# Make sure environment variables are set
export SNIPEIT_URL="https://your-snipeit-instance.com"
export SNIPEIT_TOKEN="your-api-token-here"

# Run the server
python server.py

方法2：使用FastMCP CLI

# With environment variables
fastmcp run server.py:mcp --transport stdio

# Or with HTTP transport for remote access
fastmcp run server.py:mcp --transport http --port 8000

可用工具

服务器提供了以下工具，用于与您的Snipe-IT实例进行交互：

1. manage_assets

具备增删改查（CRUD）操作的综合资产管理。

行动：

• create创建一个新资产
• get通过ID、资产标签或序列号检索单个资产
• list列出资产，并支持可选的分页和过滤功能
• update更新现有资产
• delete删除一个资产

示例：

# Create an asset
{
    "action": "create",
    "asset_data": {
        "status_id": 1,
        "model_id": 5,
        "asset_tag": "LAP-001",
        "name": "Dell Laptop",
        "serial": "ABC123XYZ"
    }
}

# Get an asset by tag
{
    "action": "get",
    "asset_tag": "LAP-001"
}

# List assets
{
    "action": "list",
    "limit": 20,
    "search": "laptop"
}

2. asset_operations

对资产执行状态操作。

行动：

• checkout向用户、地点或另一个资产分配一项资源
• checkin将资产归还库存进行登记
• audit将资产标记为已审核
• restore恢复一个已软删除的资产

示例：

# Checkout asset to user
{
    "action": "checkout",
    "asset_id": 123,
    "checkout_data": {
        "checkout_to_type": "user",
        "assigned_to_id": 45,
        "expected_checkin": "2025-12-31",
        "note": "Issued for remote work"
    }
}

# Checkin asset
{
    "action": "checkin",
    "asset_id": 123,
    "checkin_data": {
        "note": "Returned in good condition"
    }
}

3. asset_files

管理资产的文件附件。

行动：

• upload将一个或多个文件上传到资产中
• list列出与某个资产相关的所有文件
• download从资源中下载特定文件
• delete从资源中删除特定文件

示例：

# Upload files
{
    "action": "upload",
    "asset_id": 123,
    "file_paths": ["/path/to/receipt.pdf", "/path/to/warranty.pdf"],
    "notes": "Purchase documentation"
}

# List files
{
    "action": "list",
    "asset_id": 123
}

4. asset_labels

为资产生成可打印的PDF标签。

示例：

# Generate labels by asset IDs
{
    "asset_ids": [123, 124, 125],
    "save_path": "/tmp/asset_labels.pdf"
}

# Generate labels by asset tags
{
    "asset_tags": ["LAP-001", "LAP-002"],
    "save_path": "/tmp/labels.pdf"
}

5. asset_maintenance

为资产创建维护记录。

示例：

{
    "action": "create",
    "asset_id": 123,
    "maintenance_data": {
        "asset_improvement": "repair",
        "supplier_id": 10,
        "title": "Screen Replacement",
        "cost": 250.00,
        "start_date": "2025-10-10",
        "completion_date": "2025-10-11",
        "notes": "Replaced cracked screen"
    }
}

6. asset_licenses

为资产获取所有已签出的许可证。

示例：

{
    "asset_id": 123
}

7. manage_consumables

具备增删改查（CRUD）操作的综合耗材管理。

行动：

• create创建一个新的消耗品
• get通过ID检索单个消耗品
• list列出可选分页和过滤的耗材
• update更新现有耗材
• delete删除耗材

示例：

# Create a consumable
{
    "action": "create",
    "consumable_data": {
        "name": "USB-C Cable",
        "qty": 50,
        "category_id": 3,
        "min_amt": 10
    }
}

# List consumables
{
    "action": "list",
    "limit": 20,
    "search": "cable"
}

与MCP客户端的集成

Claude Desktop（可译为“Claude桌面版”）

将此配置添加到您的Claude桌面配置文件中：

位置：

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

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

光标

将此添加到您的Cursor MCP设置中：

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

建筑学

该服务器是使用以下技术构建的：

• FastMCP一个用于构建MCP服务器的Python框架
• SnipeIT Python APISnipe-IT API的Python客户端库
• Pydantic（发音类似“Pydantic”，无直接对应中文译名，通常保留原名）数据验证和设置管理

工具设计

服务器将操作整合为最少数量的工具：

• 用于资产CRUD操作的单一工具（manage_assets)
• 资产状态操作的单一工具asset_operations)
• 针对特定功能（文件、标签、维护、许可证）的专用工具
• 用于消耗品增删改查（CRUD）操作的单一工具manage_consumables）

这一设计在提供全面功能的同时，最大限度地减轻了人工智能助手的认知负担。

错误处理

所有工具都返回带有成功状态的结构化响应：

{
  "success": true,
  "action": "create",
  "asset": {
    "id": 123,
    "asset_tag": "LAP-001",
    "name": "Dell Laptop"
  }
}

错误响应包含描述性信息：

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

故障排除

认证错误

问题： “身份验证失败”错误

解决方案：

• 验证您的Snipe-IT网址是否正确且可访问
• 请检查您的API令牌是否有效且未过期
• 确保令牌具有适当的权限

连接错误

问题： 无法连接到 Snipe-IT 实例

解决方案：

• 验证URL是否正确（包括 https:// 或者 http://）
• 检查网络连接
• 确保Snipe-IT实例正在运行且可访问

工具执行错误

问题： 工具返回验证错误

解决方案：

• 检查是否提供了必填字段（例如。， status_id 并且 model_id （用于资产创建）
• 验证外键ID是否存在（例如，category_id、model_id）
• 查阅工具文档以了解所需参数

环境变量问题

问题： “Snipe-IT凭据未配置”错误

解决方案：

• 确保 SNIPEIT_URL 并且 SNIPEIT_TOKEN 在您的环境中已设置
• 如果使用 .env 文件，确保它位于正确的位置
• 在运行服务器之前，检查变量是否已导出

发展

项目结构

snipeit-mcp/
├── server.py           # Main MCP server implementation
├── pyproject.toml      # Project configuration
├── README.md           # This file
├── .gitignore         # Git ignore rules
└── .venv/             # Virtual environment (created by uv)

在开发模式下运行

# Activate virtual environment
source .venv/bin/activate

# Run with debug logging
export LOG_LEVEL=DEBUG
python server.py

许可证

此项目作为现有资源提供，用于与Snipe-IT库存管理系统配合使用。

贡献

欢迎投稿！请：

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支
3. 做出你的更改
4. 提交一个拉取请求

支持

对于以下相关问题：

• 这个MCP服务器在这个仓库中打开一个问题（或议题）
• Snipe-IT（注：这是一个软件名称，直接翻译为中文可能无特定含义，通常保留原名或根据上下文意译，此处为保持原样给出直译，实际使用中可能需根据具体情况调整）访问 Snipe-IT 支持
• FastMCP参观 FastMCP 文档

致谢

• 用……建造/构建 FastMCP
• 用途 SnipeIT Python API（SnipeIT Python应用程序接口） 用于与Snipe-IT集成
• 专为……设计 Snipe-IT（可译为“斯奈普-IT”或根据具体语境简化为“IT资产追踪系统”等，但直接音译“斯奈普-IT”更为常见，若需更具体含义，需结合上下文） 资产管理系统