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:
- Log in to your Snipe-IT instance
- Go to your user profile (click your name in the top right)
- Navigate to "API Tokens" or "Personal Access Tokens"
- 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 assetget: Retrieve a single asset by ID, asset tag, or serial numberlist: List assets with optional pagination and filteringupdate: Update an existing assetdelete: 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 assetcheckin: Check in an asset back to inventoryaudit: Mark an asset as auditedrestore: 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 assetlist: List all files attached to an assetdownload: Download a specific file from an assetdelete: 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 consumableget: Retrieve a single consumable by IDlist: List consumables with optional pagination and filteringupdate: Update an existing consumabledelete: 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://orhttp://) - 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_idandmodel_idfor 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_URLandSNIPEIT_TOKENare set in your environment - If using a
.envfile, 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:
- Fork the repository
- Create a feature branch
- Make your changes
- 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