Skip to main content
Glama

Iconik-MCP-Server

A Model Context Protocol (MCP) server for the Iconik media asset management API. This enables AI assistants like Claude to interact with your Iconik media library.

Features

  • 143 MCP Tools - Comprehensive coverage of the Iconik API

  • Multi-Profile Support - Manage multiple Iconik domains/accounts

  • Standalone Scripts - CLI tools for common bulk operations

  • Dry Run Mode - Safely preview destructive operations

Related MCP server: Relay

Installation

# Clone the repository
git clone https://github.com/postforward/Iconik-MCP-Server.git
cd Iconik-MCP-Server

# Install dependencies
npm install

# Build
npm run build

Configuration

Create iconik-config.json in the project directory:

{
  "default_profile": "production",
  "profiles": {
    "production": {
      "name": "Production Domain",
      "app_id": "your-app-id",
      "auth_token": "your-auth-token"
    },
    "staging": {
      "name": "Staging Domain",
      "app_id": "your-staging-app-id",
      "auth_token": "your-staging-auth-token",
      "api_url": "https://preview.iconik.cloud/API/"
    }
  }
}

The config file is searched in these locations:

  1. Current working directory: ./iconik-config.json

  2. Home directory: ~/.iconik-config.json

  3. Package directory

Option 2: Environment Variables

For a single profile, use environment variables:

export ICONIK_APP_ID=your-app-id
export ICONIK_AUTH_TOKEN=your-auth-token
export ICONIK_API_URL=https://app.iconik.io/API/  # Optional

Or create a .env file:

ICONIK_APP_ID=your-app-id
ICONIK_AUTH_TOKEN=your-auth-token

Running

Stdio (default)

For local use with Claude Code, Cursor, Claude Desktop, and other MCP clients:

node dist/index.js

HTTP

For remote or containerized deployment via Streamable HTTP:

MCP_TRANSPORT=http node dist/index.js

Endpoints:

  • POST /mcp — MCP protocol (new session or existing via mcp-session-id header)

  • GET /mcp — SSE stream for existing session

  • DELETE /mcp — Close session

  • GET /health — Health check

Access Levels

MCP_ACCESS_LEVEL controls which tools are registered at startup. Defaults to read for safety.

Level

Tools

Count

read

list, get, search, check

85

readwrite

read + create, update, bulk

126

full

readwrite + delete, purge

143

# Read-only (default)
node dist/index.js

# Read + write
MCP_ACCESS_LEVEL=readwrite node dist/index.js

# Full access
MCP_ACCESS_LEVEL=full node dist/index.js

Docker

# Build and run (read-only by default)
docker compose up --build

# With write access
MCP_ACCESS_LEVEL=readwrite docker compose up --build

# Full access
MCP_ACCESS_LEVEL=full docker compose up --build

Environment variables:

  • ICONIK_APP_ID (required)

  • ICONIK_AUTH_TOKEN (required)

  • MCP_ACCESS_LEVEL (default read)

  • MCP_PORT (default 8000)

Usage with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "iconik": {
      "command": "node",
      "args": ["/path/to/Iconik-MCP-Server/dist/index.js"],
      "env": {
        "ICONIK_APP_ID": "your-app-id",
        "ICONIK_AUTH_TOKEN": "your-auth-token",
        "MCP_ACCESS_LEVEL": "readwrite"
      }
    }
  }
}

Then restart Claude Desktop.

MCP Tools

The server provides tools organized by category:

Assets

  • search_assets - Search for assets with filters

  • get_asset - Get asset details

  • create_asset - Create a new asset

  • update_asset - Update asset properties

  • delete_asset - Delete an asset

  • get_asset_proxies - List proxy files

  • delete_proxies_by_collection - Bulk delete proxies

  • And 30+ more asset tools...

Collections

  • list_collections - List all collections

  • get_collection - Get collection details

  • create_collection - Create a collection

  • get_collection_contents - List collection contents

  • add_to_collection - Add assets to collection

Metadata

  • get_asset_metadata - Get asset metadata

  • update_asset_metadata - Update metadata values

  • list_metadata_views - List available views

  • get_metadata_view - Get view schema

Files & Storage

  • list_storages - List storage locations

  • get_asset_files - List asset files

  • create_file - Create file record

Jobs & Transcoding

  • list_jobs - List transcoding jobs

  • get_job - Get job status

  • create_transcode_job - Start transcode

Users & Shares

  • list_users - List users

  • list_shares - List shared links

  • create_share - Create share link

Standalone Scripts

Run scripts directly for bulk operations:

npx ts-node scripts/smart-search.ts search "interview" --type=video --transcripts
npx ts-node scripts/smart-search.ts export "*" ./all-assets.csv --limit=500
npx ts-node scripts/smart-search.ts recent --limit=10 --profile=staging

Delete Proxies

# Dry run (preview)
npx ts-node scripts/delete-proxies.ts collection <collection_id>

# Actually delete
npx ts-node scripts/delete-proxies.ts collection <collection_id> --live

# Use specific profile
npx ts-node scripts/delete-proxies.ts collection <id> --profile=production --live

Storage Audit

npx ts-node scripts/storage-audit.ts
npx ts-node scripts/storage-audit.ts --profile=production

Archive Health Report

npx ts-node scripts/archive-health-report.ts

Bulk Metadata Update

# List available metadata views
npx ts-node scripts/metadata-bulk-update.ts list-views

# Update by collection (dry run)
npx ts-node scripts/metadata-bulk-update.ts collection <collection_id> <view_id> '{"field":"value"}'

# Update from CSV
npx ts-node scripts/metadata-bulk-update.ts csv ./updates.csv <view_id> --live

Getting Your Iconik Credentials

  1. Log in to your Iconik domain

  2. Go to Admin → Settings → Applications

  3. Create a new application or use an existing one

  4. Copy the App ID and generate an Auth Token

API Reference

This MCP server wraps the Iconik API. See their documentation for detailed endpoint information.

License

ISC

Contributing

Contributions welcome! Please open an issue or PR.

Available Tools

85 tools
check_collection_archive_healthA

Scan a collection and report archive health: group assets by archive_status, flag ARCHIVING stuck >24h, list FAILED_TO_ARCHIVE assets.

Inputs: collection_id (required).

export_segments_srtB

Export asset segments as SRT subtitle format

Inputs: asset_id (required).

export_segments_vttB

Export asset segments as WebVTT subtitle format

Inputs: asset_id (required).

get_analysis_profileA

Get details of a specific analysis profile

Inputs: profile_id (required).

get_assetB

Get detailed information about a specific asset by ID

Inputs: asset_id (required), include_users, include_collections.

get_asset_approvalB

Get approval status for an asset

Inputs: asset_id (required).

get_asset_fileC

Get details of a specific file

Inputs: file_id (required), asset_id (required).

get_asset_file_setC

Get details of a specific file set

Inputs: asset_id (required), file_set_id (required).

get_asset_file_set_detailsC

Get a combined view of all file sets for an asset with storage names and file records

Inputs: asset_id (required).

get_asset_formatC

Get details of a specific format

Inputs: asset_id (required), format_id (required).

get_asset_historyA

Get the history/audit log for an asset

Inputs: asset_id (required), page, per_page.

get_asset_keyframeC

Get details of a specific keyframe

Inputs: asset_id (required), keyframe_id (required).

get_asset_metadataB

Get all metadata views and values for an asset

Inputs: asset_id (required).

get_asset_metadata_viewC

Get metadata for a specific view

Inputs: view_id (required), asset_id (required).

get_asset_proxyB

Get details of a specific proxy

Inputs: asset_id (required), proxy_id (required).

get_asset_segmentB

Get a specific segment by ID

Inputs: asset_id (required), segment_id (required).

get_asset_sharesA

Get all shares for a specific asset

Inputs: asset_id (required).

get_asset_versionB

Get details of a specific asset version

Inputs: asset_id (required), version_id (required).

get_collectionC

Get detailed information about a specific collection

Inputs: collection_id (required).

get_collection_ancestorsA

Get all ancestor collections (parent hierarchy)

Inputs: collection_id (required).

get_collection_contentsA

Get the contents (assets and sub-collections) of a collection

Inputs: collection_id (required), page, per_page, content_types.

get_collection_full_pathC

Get the full path of a collection (breadcrumb)

Inputs: collection_id (required).

get_collection_metadataB

Get all metadata views and values for a collection

Inputs: collection_id (required).

get_collection_sharesB

Get all shares for a specific collection

Inputs: collection_id (required).

get_collection_sizeA

Get the total size of all files in a collection

Inputs: collection_id (required).

get_collection_subcollectionsA

Get direct child sub-collections

Inputs: collection_id (required).

get_current_userA

Get the currently authenticated user

Inputs: no named parameters.

get_export_locationB

Get details of a specific export location

Inputs: export_location_id (required).

get_file_download_urlA

Get a temporary download URL for an original file

Inputs: file_id (required), asset_id (required).

get_file_mediainfoB

Get mediainfo/technical metadata for a file

Inputs: file_id (required), asset_id (required).

get_groupC

Get details of a specific group

Inputs: group_id (required).

get_jobC

Get details of a specific job

Inputs: job_id (required).

get_keyframe_public_urlB

Get a public URL for a keyframe image

Inputs: asset_id (required), keyframe_id (required).

get_metadata_fieldC

Get details of a specific metadata field

Inputs: field_name (required).

get_metadata_viewA

Get details of a specific metadata view including its fields

Inputs: view_id (required).

get_proxy_download_urlB

Get a temporary download URL for a proxy file

Inputs: asset_id (required), proxy_id (required).

get_proxy_public_urlA

Get a public streaming URL for a proxy (if available)

Inputs: asset_id (required), proxy_id (required).

get_segments_textB

Get all segment text content as plain text

Inputs: asset_id (required).

get_shareC

Get details of a specific share

Inputs: share_id (required), object_id (required), object_type (required).

get_share_urlB

Get the public URL for a share

Inputs: object_id (required), object_type (required).

get_storageA

Get details of a specific storage location

Inputs: storage_id (required).

get_storage_for_purposeC

Find the default storage for a specific purpose

Inputs: purpose (required).

get_subtitle_webvttC

Get subtitle content in WebVTT format

Inputs: asset_id (required), language (required), version_id.

get_transcoderA

Get details of a specific transcoder

Inputs: transcoder_id (required).

get_transcription_propertiesC

Get transcription properties for an asset version

Inputs: asset_id (required), version_id (required).

get_transcription_subtitlesC

Get transcription as subtitles

Inputs: asset_id (required), version_id (required).

get_userC

Get details of a specific user

Inputs: user_id (required).

list_analysis_profilesA

List all analysis profiles for media processing

Inputs: no named parameters.

list_asset_filesB

List all files associated with an asset

Inputs: asset_id (required), version_id.

list_asset_file_setsB

List all file sets for an asset

Inputs: asset_id (required), version_id.

list_asset_formatsA

List all formats (ORIGINAL, PROXY, etc.) for an asset

Inputs: asset_id (required), version_id.

list_asset_keyframesA

List all keyframes/thumbnails for an asset

Inputs: asset_id (required), version_id.

list_asset_proxiesB

List all proxy files for an asset

Inputs: asset_id (required), version_id.

list_asset_relationsB

List all relations for an asset

Inputs: asset_id (required), relation_type.

list_assetsB

List all assets with pagination

Inputs: page, sort, order, per_page.

list_asset_segmentsB

List all segments (markers, chapters, transcriptions, etc.) for an asset

Inputs: asset_id (required), page, per_page, segment_type.

list_asset_subtitlesC

List all subtitle tracks for an asset

Inputs: asset_id (required), version_id.

list_asset_versionsB

List all versions of an asset

Inputs: asset_id (required).

list_child_jobsB

List child jobs of a parent job

Inputs: parent_id (required), page, status, per_page.

list_collectionsC

List all collections with pagination

Inputs: page, sort, order, per_page.

list_deleted_file_setsB

List file sets in the delete queue

Inputs: no named parameters.

list_deleted_formatsA

List formats in the delete queue

Inputs: no named parameters.

list_export_locationsA

List all configured export locations

Inputs: no named parameters.

list_file_set_filesA

List all file records in a specific file set

Inputs: asset_id (required), file_set_id (required).

list_group_membersB

List all members of a group

Inputs: group_id (required).

list_groupsB

List all groups in the system

Inputs: page, per_page.

list_jobsC

List all jobs with pagination

Inputs: page, type, status, per_page.

list_job_stepsA

List all steps/tasks for a job

Inputs: job_id (required).

list_metadata_fieldsB

List all available metadata fields

Inputs: _placeholder.

list_metadata_viewsB

List all available metadata views

Inputs: _placeholder.

list_relation_typesA

List all available asset relation types

Inputs: no named parameters.

list_sharesC

List all shares

Inputs: page, per_page.

list_share_usersA

List users who have access to a share

Inputs: share_id (required), object_id (required), object_type (required).

list_storage_filesC

List files in a storage location

Inputs: storage_id (required), page, per_page.

list_storagesB

List all configured storage locations

Inputs: no named parameters.

list_storage_transfers_fromA

List pending transfers from a storage

Inputs: storage_id (required).

list_storage_transfers_toA

List pending transfers to a storage

Inputs: storage_id (required).

list_transcodersA

List all configured transcoders

Inputs: no named parameters.

list_user_groupsA

List all groups a user belongs to

Inputs: user_id (required).

list_usersC

List all users in the system

Inputs: page, per_page.

search_assetsB

Search for assets in Iconik using a query string

Inputs: query (required), page, sort, order, +3 more.

search_by_date_rangeC

Search assets created within a date range

Inputs: end_date (required), start_date (required), page, query, +2 more.

search_by_metadataA

Search assets by specific metadata field values

Inputs: value (required), metadata_field (required), page, per_page.

search_facetedC

Perform a faceted search to get aggregations/counts

Inputs: query (required), facets (required), doc_types.

search_segmentsB

Search for segments across all assets

Inputs: query (required), page, per_page, segment_type.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 85 tools

    Disambiguation4/5

    Most tools map cleanly to distinct resources and actions, with a consistent list/get/search hierarchy. A few pairs like get_asset_file_set_details vs get_asset_file_set and get_subtitle_webvtt vs get_transcription_subtitles have somewhat overlapping boundaries, but the descriptions generally make the intended target clear.

    Naming Consistency4/5

    The set overwhelmingly follows a snake_case verb_noun pattern: list_*, get_*, search_*. Minor deviations such as check_collection_archive_health, search_faceted, and get_storage_for_purpose break the pattern slightly but do not make the naming chaotic.

    Tool Count1/5

    With 85 tools, the surface is extremely large and exceeds even the 50+ threshold for an extreme mismatch. Many serial getters for closely related sub-resources like proxies, keyframes, formats, and file sets could be consolidated, making the tool set overwhelming for agents.

    Completeness2/5

    Read coverage is broad: assets, collections, metadata, storage, jobs, users, groups, and shares are all represented. However, the surface is almost entirely read-only; there are no create, update, delete, upload, ingest, metadata-editing, share-management, or job-control tools, so core media management workflows cannot be completed.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers