MCP Iconik

MCP Iconik

MCP (Model Context Protocol) server providing tools for the Iconik media asset management API.

Features

• Dual Transport Support: Both SSE (Server-Sent Events) and Streamable HTTP transports
• Docker Ready: Runs as a containerized service
• Comprehensive API Coverage: Tools for all major Iconik API endpoints
• Claude Code CLI Compatible: Works with Claude Code CLI
• LMStudio Compatible: Works with LMStudio via HTTP transport

Available Tools

Assets

• iconik_list_assets - List assets with pagination
• iconik_get_asset - Get asset details
• iconik_create_asset - Create new asset
• iconik_update_asset - Update asset properties
• iconik_delete_asset - Delete an asset

Collections

• iconik_list_collections - List collections
• iconik_get_collection - Get collection details
• iconik_create_collection - Create new collection
• iconik_update_collection - Update collection
• iconik_delete_collection - Delete collection
• iconik_get_collection_contents - Get collection contents
• iconik_add_to_collection - Add items to collection

Search

• iconik_search - Search assets and collections
• iconik_list_saved_searches - List saved searches
• iconik_get_saved_search - Get/execute saved search
• iconik_create_saved_search - Create saved search
• iconik_delete_saved_search - Delete saved search

Files & Storage

• iconik_list_storages - List storage locations
• iconik_get_storage - Get storage details
• iconik_get_asset_files - Get asset files
• iconik_get_asset_formats - Get asset formats
• iconik_get_asset_proxies - Get asset proxies
• iconik_get_asset_keyframes - Get asset keyframes

Metadata

• iconik_list_metadata_views - List metadata views
• iconik_get_metadata_view - Get metadata view
• iconik_get_asset_metadata - Get asset metadata
• iconik_update_asset_metadata - Update asset metadata

Jobs

• iconik_list_jobs - List jobs
• iconik_get_job - Get job details
• iconik_create_job - Create job
• iconik_update_job - Update job

Users & Groups

• iconik_list_users - List users
• iconik_get_user - Get user details
• iconik_get_current_user - Get current user
• iconik_list_groups - List groups
• iconik_get_group - Get group details
• iconik_list_shares - List shares
• iconik_get_share - Get share details
• iconik_list_projects - List projects
• iconik_get_project - Get project details
• iconik_list_webhooks - List webhooks
• iconik_get_webhook - Get webhook details

Generic

• iconik_api_request - Make generic API requests
• iconik_get_acls - Get object ACLs
• iconik_update_acls - Update object ACLs

Quick Start

Using Docker Compose

1. Create a .env file with your Iconik credentials:

# Option 1: Use JWT API token
ICONIK_API=your_jwt_token_here

# Option 2: Use App ID and Auth Token
ICONIK_APP_ID=your_app_id
ICONIK_AUTH_TOKEN=your_auth_token

# Optional: Custom Iconik URL (default: https://app.iconik.io)
ICONIK_URL=https://app.iconik.io

1. Build and run:

docker-compose up -d

1. The server will be available at:

• SSE endpoint: http://localhost:8000/sse
• HTTP endpoint: http://localhost:8000/mcp
• Health check: http://localhost:8000/health

Using Docker Directly

docker build -t mcp-iconik .
docker run -d \
  -p 8000:8000 \
  -e ICONIK_API=your_jwt_token \
  --name mcp-iconik \
  mcp-iconik

Local Development

# Install dependencies
pip install -e .

# Run the server
python -m mcp_iconik.server

Configuration with Claude Code CLI

Add to your Claude Code configuration (~/.claude/mcp.json):

{
  "mcpServers": {
    "iconik": {
      "url": "http://localhost:8000/sse",
      "transport": "sse"
    }
  }
}

Or for HTTP transport:

{
  "mcpServers": {
    "iconik": {
      "url": "http://localhost:8000/mcp",
      "transport": "http"
    }
  }
}

Configuration with LMStudio

LMStudio uses HTTP transport. Configure the MCP server URL as:

http://localhost:8000/mcp

API Endpoints

| Endpoint | Transport | Description | |----------|-----------|-------------| | /sse | SSE | Server-Sent Events connection | | /messages/ | SSE | SSE message handler | | /mcp | HTTP | Streamable HTTP transport | | /health | HTTP | Health check endpoint |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | ICONIK_API | JWT API token (preferred) | - | | ICONIK_APP_ID | Application ID | - | | ICONIK_AUTH_TOKEN | Auth token | - | | ICONIK_URL | Iconik base URL | https://app.iconik.io | | HOST | Server host | 0.0.0.0 | | PORT | Server port | 8000 | | DEBUG | Enable debug mode | false |

Getting Iconik Credentials

1. Log in to your Iconik instance
2. Go to Admin Panel > Settings > Application Tokens
3. Create a new application or use an existing one
4. Create a new authentication token
5. Copy the App ID and token

License

MIT