Snipe-IT MCP Server

A Model Context Protocol (MCP) server for managing Snipe-IT inventory systems. This server provides AI assistants with tools to perform CRUD operations on assets and consumables in your Snipe-IT instance.

Features

• Comprehensive Asset Management: Create, read, update, delete, and search assets
• Asset Operations: Checkout, checkin, audit, and restore assets
• File Management: Upload, download, list, and delete asset attachments
• Label Generation: Generate printable PDF labels for assets
• Maintenance Tracking: Create maintenance records for assets
• License Management: View licenses associated with assets
• Consumable Management: Full CRUD operations for consumables
• Type-Safe: Built with Pydantic models for robust validation
• Error Handling: Comprehensive error handling and logging

Requirements

• Python 3.11 or higher
• UV package manager
• A running Snipe-IT instance with API access
• Snipe-IT API token with appropriate permissions

Installation

1. Clone or download this repository

git clone <repository-url>
cd snipeit-mcp

2. Install dependencies using 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

Note: The first time you run uv sync, it will install the snipeit-python-api from the local path at /Users/work/Documents/Projects/Inventory/snipeit-python-api. Make sure that directory exists.

Alternatively, if you want to manually set up:

# Create virtual environment
uv venv --python 3.11

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

3. Configure environment variables

Create a .env file or export these environment variables:

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

Or create a .env file:

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

To get a Snipe-IT API token:

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

Usage

Running the Server

Method 1: Direct Python execution

# 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

Method 2: Using 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

Available Tools

The server provides the following tools for interacting with your Snipe-IT instance:

1. manage_assets

Comprehensive asset management with CRUD operations.

Actions:

• create: Create a new asset
• get: Retrieve a single asset by ID, asset tag, or serial number
• list: List assets with optional pagination and filtering
• update: Update an existing asset
• delete: Delete an asset

Example:

# 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

Perform state operations on assets.

Actions:

• checkout: Check out an asset to a user, location, or another asset
• checkin: Check in an asset back to inventory
• audit: Mark an asset as audited
• restore: Restore a soft-deleted asset

Example:

# 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

Manage file attachments for assets.

Actions:

• upload: Upload one or more files to an asset
• list: List all files attached to an asset
• download: Download a specific file from an asset
• delete: Delete a specific file from an asset

Example:

# 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

Generate printable PDF labels for assets.

Example:

# 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

Create maintenance records for assets.

Example:

{
    "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

Get all licenses checked out to an asset.

Example:

{
    "asset_id": 123
}

7. manage_consumables

Comprehensive consumable management with CRUD operations.

Actions:

• create: Create a new consumable
• get: Retrieve a single consumable by ID
• list: List consumables with optional pagination and filtering
• update: Update an existing consumable
• delete: Delete a consumable

Example:

# 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"
}

Integration with MCP Clients

Claude Desktop

Add this configuration to your Claude Desktop config file:

Location:

• 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

Add this to your Cursor MCP settings:

{
  "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"
      }
    }
  }
}

Architecture

The server is built using:

• FastMCP: A Python framework for building MCP servers
• snipeit-python-api: Python client library for Snipe-IT API
• Pydantic: Data validation and settings management

Tool Design

The server consolidates operations into a minimal number of tools:

• Single tool for Asset CRUD operations (manage_assets)
• Single tool for Asset state operations (asset_operations)
• Specialized tools for specific features (files, labels, maintenance, licenses)
• Single tool for Consumable CRUD operations (manage_consumables)

This design minimizes the cognitive load on AI assistants while providing comprehensive functionality.

Error Handling

All tools return structured responses with success status:

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

Error responses include descriptive messages:

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

Troubleshooting

Authentication Errors

Problem: "Authentication failed" error

Solution:

• Verify your Snipe-IT URL is correct and accessible
• Check that your API token is valid and not expired
• Ensure the token has appropriate permissions

Connection Errors

Problem: Cannot connect to Snipe-IT instance

Solution:

• Verify the URL is correct (include https:// or http://)
• Check network connectivity
• Ensure Snipe-IT instance is running and accessible

Tool Execution Errors

Problem: Tool returns validation errors

Solution:

• Check that required fields are provided (e.g., status_id and model_id for asset creation)
• Verify foreign key IDs exist (e.g., category_id, model_id)
• Review the tool documentation for required parameters

Environment Variable Issues

Problem: "Snipe-IT credentials not configured" error

Solution:

• Ensure SNIPEIT_URL and SNIPEIT_TOKEN are set in your environment
• If using a .env file, make sure it's in the correct location
• Check that the variables are exported before running the server

Development

Project Structure

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)

Running in Development Mode

# Activate virtual environment
source .venv/bin/activate

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

License

This project is provided as-is for use with Snipe-IT inventory management systems.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Support

For issues related to:

• This MCP Server: Open an issue in this repository
• Snipe-IT: Visit Snipe-IT support
• FastMCP: Visit FastMCP documentation

Acknowledgments

• Built with FastMCP
• Uses snipeit-python-api for Snipe-IT integration
• Designed for Snipe-IT asset management system