Image Relay MCP Server

The complete Model Context Protocol server for Image Relay's digital asset management platform.
101 tools spanning files, folders, collections, products, users, permissions, and more.

101 tools • full API v2 coverage • DAM + PIM

Quick Start • MCPB Download • All 101 Tools • Configuration • API Coverage

---

Why This Exists

Digital asset management is the backbone of brand operations — but DAM platforms like Image Relay are designed for human workflows, not programmatic access. Finding the right asset means navigating folder trees, applying filters, and manually downloading files. Uploading a batch of assets means repetitive form-filling.

This server gives your AI assistant full access to your Image Relay DAM through natural language. Browse folders, search files, upload assets, manage metadata, organize collections, administer users, and configure webhooks — all through conversation. Built on the Model Context Protocol, it works with Claude Desktop, Claude Code, and any MCP-compatible client.

Quick Start

Install with MCPB

For Claude Desktop and other MCPB-compatible clients, download the local bundle from the v2.0.2 release:

Download imagerelay-mcp-server-2.0.2.mcpb

The bundle includes the Image Relay favicon, production runtime dependencies, and setup prompts for your API key and optional subdomain.

1. Get an API Key

In Image Relay, go to My Account > API Keys and generate a new key.

2. Install

Claude Desktop — add to your claude_desktop_config.json:

{
  "mcpServers": {
    "imagerelay": {
      "command": "npx",
      "args": ["-y", "imagerelay-mcp-server"],
      "env": {
        "IMAGERELAY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code — add to your ~/.claude.json or project settings:

{
  "mcpServers": {
    "imagerelay": {
      "command": "npx",
      "args": ["-y", "imagerelay-mcp-server"],
      "env": {
        "IMAGERELAY_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Start talking to your DAM

"Show me what's in the Marketing Assets folder"

"Upload this logo from URL to the Brand folder with the Photo metadata template"

"Find all files uploaded after January 2024 in the Product Images folder"

"Create a collection called Q2 Campaign and add these assets to it"

Environment Variables

Variable	Required	Description
IMAGERELAY_API_KEY	Yes	Your Image Relay API key (Bearer token)
IMAGERELAY_SUBDOMAIN	No	Custom subdomain if not using api.imagerelay.com

1Password Integration

If IMAGERELAY_API_KEY is not set in the environment, the server automatically attempts to resolve it from 1Password CLI:

op://Development/Image Relay API Key/credential

This means you can skip setting the env var entirely if you have op installed and a service account or session active. The fallback adds ~1-2s to startup and is silently skipped if 1Password is unavailable.

Complete Tool Reference

Library Management

Files — 15 tools

Tool	Description
ir_get_files	List files in a folder with filters (date, type, search, recursive)
ir_get_file	Get full details for a specific file
ir_upload_file_from_url	Upload a file by providing a source URL
ir_update_file_metadata	Update metadata terms on a file (append or overwrite)
ir_update_file_tags	Add or remove keyword tags on a file
ir_move_file	Move a file to one or more folders
ir_duplicate_file	Copy a file to another folder with optional metadata
ir_create_synced_file	Create synced copies across multiple folders
ir_delete_file	Delete a file
ir_get_file_types	List all metadata templates
ir_get_file_type	Get a specific metadata template
ir_create_upload_job	Create a chunked upload job for large files
ir_check_upload_job_status	Check the status of a chunked upload job
ir_create_file_version	Start a version update (get upload UUID)
ir_complete_file_version	Complete a file version upload after chunks are sent

Folders — 7 tools

Tool	Description
ir_get_root_folder	Get the root folder (starting point for navigation)
ir_get_folders	List all folders with pagination
ir_get_folder	Get details for a specific folder
ir_get_child_folders	List immediate children of a folder
ir_create_folder	Create a new folder
ir_update_folder	Rename a folder
ir_delete_folder	Delete a folder

Collections — 6 tools

Tool	Description
ir_get_collections	List all collections
ir_get_collection	Get a specific collection
ir_get_collection_files	List files in a collection
ir_create_collection	Create a collection with optional initial assets
ir_update_collection	Update name or add assets to a collection
ir_delete_collection	Delete a collection (files are preserved)

Keywords & Tagging — 9 tools

Tool	Description
ir_get_keyword_sets	List all keyword sets (tag groups)
ir_get_keyword_set	Get a specific keyword set
ir_create_keyword_set	Create a new keyword set
ir_update_keyword_set	Rename a keyword set
ir_get_keywords	List keywords in a set
ir_get_keyword	Get a specific keyword
ir_create_keyword	Create a keyword in a set
ir_update_keyword	Rename a keyword
ir_delete_keyword	Delete a keyword

Sharing & Distribution

Quick Links — 5 tools

Tool	Description
ir_get_quick_links	List all download/share links
ir_get_quick_link	Get a specific quick link
ir_get_user_quick_links	List quick links for a specific user
ir_create_quick_link	Create a download link for a file
ir_delete_quick_link	Delete a quick link

Folder Links — 4 tools

Tool	Description
ir_get_folder_links	List all folder sharing links
ir_get_folder_link	Get a specific folder link
ir_create_folder_link	Create a sharing link for a folder
ir_delete_folder_link	Delete a folder link

Upload Links — 4 tools

Tool	Description
ir_get_upload_links	List all upload links
ir_get_upload_link	Get a specific upload link
ir_create_upload_link	Create an upload link for external contributors
ir_delete_upload_link	Delete an upload link

Product Information Management (PIM)

Products — 8 tools

Tool	Description
ir_get_products	List products with filters (name, category, variants, template, dimension)
ir_get_product	Get a specific product
ir_get_product_catalog	Get the catalog a product belongs to
ir_create_product	Create a product with SKU, dimensions, and custom attributes
ir_update_product	Update product details
ir_delete_product	Delete a product
ir_get_product_variants	List all variants for a product
ir_get_product_variant	Get a specific variant

Variants — 3 tools

Tool	Description
ir_create_variant	Create a variant with dimension options and custom attributes
ir_update_variant	Update a variant
ir_delete_variant	Delete a variant

Catalogs — 6 tools

Tool	Description
ir_get_catalogs	List all product catalogs
ir_get_catalog	Get a specific catalog by ID
ir_create_catalog	Create a catalog with optional summary
ir_update_catalog	Rename a catalog
ir_delete_catalog	Delete a catalog
ir_get_catalog_products	List products in a catalog

Categories, Templates & Dimensions — 12 tools

Tool	Description
ir_get_categories	List product categories
ir_get_category	Get a specific category
ir_get_templates	List product templates
ir_get_template	Get a specific template
ir_create_template	Create a product template
ir_update_template	Update a template
ir_get_channel_template_mappings	Get channel template mappings
ir_get_dimensions	List product dimensions
ir_get_dimension	Get a specific dimension
ir_create_dimension	Create a dimension
ir_update_dimension	Update a dimension
ir_add_dimension_option	Add a value to a dimension

Custom Attributes — 4 tools

Tool	Description
ir_get_custom_attributes	List all custom attributes
ir_get_custom_attribute	Get a specific custom attribute
ir_create_custom_attribute	Create a custom attribute
ir_update_custom_attribute	Update a custom attribute

Administration

Users — 4 tools

Tool	Description
ir_get_me	Get the authenticated user's profile
ir_get_users	List all users
ir_get_user	Get a specific user
ir_search_users	Search by name or email

Invited Users — 5 tools

Tool	Description
ir_get_invited_users	List pending invitations
ir_get_invited_user	Get a specific invitation
ir_invite_user	Invite a new user
ir_delete_invited_user	Cancel an invitation
ir_create_sso_user	Create a user via SSO

Permissions — 3 tools

Tool	Description
ir_get_permissions	List permission groups
ir_get_permission	Get a specific permission group
ir_update_user_permission	Change a user's permission group

Webhooks — 6 tools

Tool	Description
ir_get_supported_webhooks	List all supported event types
ir_get_webhooks	List configured webhooks
ir_get_webhook	Get a specific webhook
ir_create_webhook	Create a webhook
ir_update_webhook	Update a webhook's URL or notification emails
ir_delete_webhook	Delete a webhook

Features

• Complete API coverage — 101 tools covering every JSON endpoint in Image Relay's v2 API
• Smart pagination — Handles both response-body and Link-header pagination automatically
• Retry with backoff — Automatic retry on 429/502/503 with exponential backoff and Retry-After support
• Dual output formats — Every tool supports markdown (human-friendly) and json (machine-friendly) output
• Detailed error messages — Clear, actionable error descriptions for auth failures, rate limits, and more
• MCP annotations — Read-only, destructive, and idempotent hints for safe AI tool use

Rate Limits

Image Relay allows 5 requests per second per IP. The server handles rate limiting automatically:

• 429 responses trigger automatic retry with backoff
• Retry-After headers are respected when present
• Maximum 3 retries with up to 30 second delays

Architecture

src/
├── index.ts                    Server entry point and tool registration
├── constants.ts                API base URLs and shared constants
├── op-fallback.ts              Optional 1Password credential resolution
├── schemas/
│   └── common.ts               Shared Zod schemas for pagination and formats
├── services/
│   ├── api-client.ts           Axios client, auth headers, pagination, retries
│   └── formatter.ts            Markdown and JSON response formatting
└── tools/
    ├── files.ts                Asset search, upload from URL, metadata updates
    ├── folders.ts              Folder navigation and organization
    ├── collections.ts          Collection CRUD and file assignment
    ├── products.ts             PIM products, variants, catalogs, dimensions
    ├── users.ts                User lookup and administration
    ├── permissions.ts          Permission groups and user access
    └── webhooks.ts             Webhook discovery and management

Design Decisions

• Single API client keeps authentication, retry behavior, and pagination consistent across all 101 tools.
• Tool modules mirror Image Relay domains so DAM, sharing, PIM, administration, and webhook behavior stay easy to audit.
• Markdown and JSON response modes make the same tools useful for human review and downstream automation.
• 1Password fallback is optional so public installs work with plain environment variables, while private setups can stay credential-free.

Development

# Clone and install
git clone https://github.com/oliverames/imagerelay-mcp-server.git
cd imagerelay-mcp-server
npm install

# Run tests
npm test

# Dev mode (auto-restart on changes)
IMAGERELAY_API_KEY=your-key npm run dev

# Build
npm run build

API Coverage

This server implements the full Image Relay API v2 with two intentional exceptions:

Feature	Status	Notes
Library API (files, folders, collections)	Complete	All endpoints
Sharing (quick links, folder links, upload links)	Complete	All endpoints
Keywording & metadata	Complete	All endpoints
Users, permissions, invitations	Complete	All endpoints
Webhooks	Complete	All endpoints
PIM (products, variants, catalogs, dimensions)	Complete	All endpoints
Custom attributes & templates	Complete	All endpoints
Chunked file uploads	Not included	Multi-step stateful workflow; use ir_upload_file_from_url instead
Update asset thumbnail	Not included	Requires binary upload (application/octet-stream)

License

MIT

_{Not affiliated with or endorsed by Image Relay.}

---

_{Built by Oliver Ames in Vermont • GitHub • LinkedIn • Bluesky}