An ImageKit MCP for media workflows that reach past ImageKit
Connect one private API key and the ImageKit media library becomes workflow steps: upload files from a URL, search and tag assets, manage folders and version history, define custom metadata fields, and purge the CDN cache. An AI agent can keep the library organized, a form submission can become a stored asset with a delivery URL, and the results land next to your tasks and databases instead of in a dashboard tab.
What the ImageKit MCP connector does
The ImageKit connector for Mattering Automations is 32 nodes across ImageKit's media library and Upload APIs: list and search assets with the searchQuery language, read and update file details, copy, move, and rename files and folders, walk and restore version history, add and remove tags in 50-file batches, define and manage custom metadata fields, read technical metadata like EXIF and perceptual hashes, purge the CDN cache with status polling, read account usage, and upload new files by handing ImageKit a URL to fetch server-side. One private API key authenticates all of it.
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and any MCP-capable assistant can use them, alongside Matter, the AI assistant built into the platform. An agent can search the library for untagged uploads from the last week, tag them in batches, move them into the right folders, and set custom metadata values, without anyone opening the ImageKit dashboard.
ImageKit publishes its own official MCP server, hosted at api-mcp.imagekit.io and installable from npm as @imagekit/api-mcp, currently in public preview (beta) per ImageKit's documentation. It is good at what it is for: a direct line from an assistant to ImageKit. This connector is for the other half of the job, where ImageKit is one step among many. On the Mattering canvas the same nodes sit next to every other connector and the platform itself, so a webhook can upload an image and then write its delivery URL into a Mattering database, an agent's bulk cleanup can wait behind a human approval step, and a usage report can open a task when a number drifts. Use whichever fits, or both.
The safety modeling is stated plainly. Of the 32 nodes, 11 read and 21 act, and five are flagged destructive: delete file, delete files in bulk, delete file version, delete folder, and delete custom metadata field. ImageKit deletes are permanent, with no trash and no restore API. Delete folder removes the folder and everything inside it, and unlike some providers ImageKit does not refuse a non-empty folder. Deleting a custom metadata field permanently retires its name, so no future field can ever reuse it. All of this is stated on the nodes themselves.
One connection, three surfaces
- Visual automations. Drag ImageKit nodes onto the canvas and wire them to triggers, conditions, and other apps.
- AI agents, yours or ours. These nodes speak MCP, the open protocol, so Claude, ChatGPT, and any MCP-capable assistant can use them, and Matter, the agent built into the platform, uses them natively.
- The whole platform. Combine with native tasks, projects, and other connectors, no middleware in between.
Every ImageKit node, ready to drop on the canvas
32 nodes, generated from the connector itself so this list always matches what ships. Expand a category to browse.
Read and query nodes 11
ImageKit: Get Account Usage
Read aggregate account usage between two dates: bandwidth bytes, media library storage bytes, video processing units, extension units, and original cache storage. The range covers startDate up to but NOT including endDate, must stay under 90 days, and returns one total per metric for the whole range (no per-day breakdown). Responses are cached by ImageKit for several hours.
ImageKit: Get Bulk Job Status
Check an asynchronous folder job (copy, move, or rename): Pending or Completed, plus the purgeRequestId when a rename requested a cache purge.
ImageKit: Get File Details
Fetch the current version of one file in full: URL, thumbnail, dimensions, tags, AI tags, custom metadata, version info, and publication state.
ImageKit: Get File Metadata
Read the technical metadata of an uploaded file: dimensions, format, density, transparency, perceptual hash (pHash), and full EXIF blocks for images; codec and duration details for video.
ImageKit: Get File Version Details
Fetch the details of one specific version of a file, including its own URL with the version query string.
ImageKit: Get Metadata from URL
Read the same technical metadata (EXIF, pHash, dimensions) for any delivery URL served through the account, including transformed URLs.
ImageKit: Get Purge Status
Check a cache purge request: Pending or Completed.
ImageKit: Get Usage Analytics
Read delivery analytics between two dates (both inclusive, span under 90 days; a beta API): request and bandwidth totals, status code and error breakdowns, top 404 assets, cache hit/miss counts, and per-country and per-format splits. All figures are totals for the whole range; there is no per-day series. Check generatedAt for data freshness.
ImageKit: List Custom Metadata Fields
List the account's custom metadata field definitions (name, label, and value schema). The id from here feeds the update and delete field nodes; the names key the customMetadata values on upload and update file.
ImageKit: List File Versions
List every version of a file, newest first, with each version's versionInfo.id (the versionId the per-version nodes take), URL, size, and timestamps.
ImageKit: List Files
List and search the media library: files, file versions, or folders, with sorting, folder scoping, and ImageKit's searchQuery language for advanced filters. Returns a bare array of asset objects; the fileId, filePath, folderPath, and url values here feed every other ImageKit node. Also the credential health check to run first in any ImageKit automation.
Action nodes 21
ImageKit: Add Tags (Bulk)
Add one or more tags to up to 50 files in one call. Existing tags are kept. Reversible with ImageKit: Remove Tags (Bulk).
ImageKit: Copy File
Copy a file into another folder, optionally with all its versions. If a file of the same name exists at the destination, the copy is appended to that file's version history. Reversible by deleting the copy.
ImageKit: Copy Folder
Copy a folder with all its nested folders and files into another folder. Runs as an asynchronous bulk job: the returned jobId feeds ImageKit: Get Bulk Job Status. Reversible by deleting the copy.
ImageKit: Create Custom Metadata Field
Define a new custom metadata field (Text, Textarea, Number, Date, Boolean, SingleSelect, or MultiSelect) that assets can then carry values for. Deleting a field later permanently retires its name, so choose names carefully.
ImageKit: Create Folder
Create a new folder under a parent path, creating missing intermediate folders automatically. Reversible with ImageKit: Delete Folder while the folder is empty.
ImageKit: Delete Custom Metadata Field
DESTRUCTIVE: delete a custom metadata field definition. The field's API name is permanently retired: no new field can ever be created with the same name. Fields referenced by a path policy cannot be deleted.
ImageKit: Delete File
DESTRUCTIVE: permanently delete one file and ALL its versions. There is no trash or restore. Cached copies on the CDN are not removed; purge them with ImageKit: Purge Cache if needed.
ImageKit: Delete File Version
DESTRUCTIVE: permanently delete one NON-CURRENT version of a file (the API refuses to delete the current version). There is no restore for a deleted version.
ImageKit: Delete Files (Bulk)
DESTRUCTIVE: permanently delete up to 100 files and all their versions in one call. There is no trash or restore. A 207 response reports per-file failures alongside the successes.
ImageKit: Delete Folder
DESTRUCTIVE: permanently delete a folder AND EVERYTHING inside it: all nested files, their versions, and all subfolders. Unlike some providers, ImageKit does NOT refuse non-empty folders, and there is no restore.
ImageKit: Move File
Move a file and all its versions into another folder. If a file of the same name exists at the destination, the moved file is appended to its version history. Reversible by moving back.
ImageKit: Move Folder
Move a folder with all its nested folders, files, and versions into another folder. Runs as an asynchronous bulk job: the returned jobId feeds ImageKit: Get Bulk Job Status. Reversible by moving back.
ImageKit: Purge Cache
Purge the CDN and internal cache for one delivery URL (asynchronous; the cache re-fills on the next request). Returns a requestId for ImageKit: Get Purge Status. Purge requests count against the account's monthly purge quota.
ImageKit: Remove AI Tags (Bulk)
Remove machine-generated AI tags from up to 50 files in one call. AI tags come from the auto-tagging extensions; removed ones can be regenerated by re-running the extension on the file.
ImageKit: Remove Tags (Bulk)
Remove one or more tags from up to 50 files in one call. Reversible with ImageKit: Add Tags (Bulk).
ImageKit: Rename File
Rename a file (all versions). Old URLs stop working, though CDN-cached copies persist unless purgeCache is set. Reversible by renaming back. A 409 means a file with the new name already exists there.
ImageKit: Rename Folder
Rename a folder; every nested asset keeps its content but gets an updated path, so old URLs stop working. Runs as an asynchronous bulk job (202): the returned jobId feeds ImageKit: Get Bulk Job Status. Reversible by renaming back.
ImageKit: Restore File Version
Restore an older version of a file as the current version. Reversible by restoring the previous current version again from the version list.
ImageKit: Update Custom Metadata Field
Update a custom metadata field's label or schema rules. The field's type and API name cannot change (type keys sent inside schema are ignored). At least one of label or schema must be provided.
ImageKit: Update File Details
Edit the current version of one file: replace its tag list, remove AI tags, set custom coordinates, set custom metadata values, or update the description. Only fields you fill are sent. Extensions and publication state are reachable via extra_body (extensions, publish).
ImageKit: Upload File from URL
Upload a file by giving ImageKit a publicly reachable HTTP or HTTPS URL to fetch server-side (the Upload API's file parameter accepts a URL natively; ImageKit must receive response headers within 8 seconds). Returns the stored file's fileId, path, and delivery URL. Reversible with ImageKit: Delete File.
Connecting ImageKit takes one credential
ImageKit authenticates server-side API requests with HTTP Basic auth: the private API key is the username and the password is empty. Keys live in the ImageKit dashboard under Developer options, then API keys. The dashboard shows two keys, and only the private key (it starts with private_) works here: the public key exists for client-side upload signature flows and authenticates nothing server-side, so the connector rejects a stored public key with an error that says exactly that. ImageKit's pricing page lists a free plan that includes the media library and API access.
Sign in to the ImageKit dashboard, open Developer options, then API keys, and copy the private key. It starts with private_. Do not copy the public key: it starts with public_ and cannot authenticate API calls.
In Mattering Automations, open Connectors, click Add Connector, choose ImageKit, and create a credential with the private key. The URL endpoint field is optional and for reference only; no node requires it.
Click Test Connection. Mattering lists one file from your media library, a read that succeeds even on an empty library, so a pass proves the key is valid.
All 32 ImageKit nodes appear in the canvas palette. Run ImageKit: List Files first: the fileId, filePath, folderPath, and url values it returns feed every other ImageKit node.
Common uses for the ImageKit MCP
Turn any URL into a stored asset
ImageKit: Upload File from URL is the ingestion workhorse: hand it a publicly reachable HTTP or HTTPS URL and ImageKit fetches the file server-side, no download step in the workflow. The node returns the stored file's fileId, path, and delivery URL, ready to write into a Mattering database or attach to a task. One physical constraint to design around: ImageKit must receive response headers from the source URL within 8 seconds, so slow origins fail the fetch.
An AI agent that keeps the media library organized
ImageKit: List Files finds the work, using the searchQuery language for filters like assets created in the last week or files over a size threshold. ImageKit: Add Tags (Bulk) and ImageKit: Remove Tags (Bulk) act on up to 50 files per call, ImageKit: Move File files assets into the right folders, and ImageKit: Update File Details sets descriptions and custom metadata values. Every step is reversible, which makes this a safe surface to hand an agent.
Custom metadata as structured asset data
ImageKit: Create Custom Metadata Field defines typed fields on the library: Text, Textarea, Number, Date, Boolean, SingleSelect, or MultiSelect. Workflows then write values per file through ImageKit: Update File Details, so an approval status, a campaign name, or a rights expiry date lives on the asset itself. One caution built into the platform: deleting a field permanently retires its name, so field definitions deserve an approval step that plain tag edits do not.
Rollbacks built into the library
Every file carries its version history. ImageKit: List File Versions shows what exists, newest first, ImageKit: Restore File Version makes an older version current again, and ImageKit: Delete File Version prunes old versions, with the API refusing to delete the current one. Because the CDN keeps serving cached copies after a restore, the honest follow-up step is ImageKit: Purge Cache on the file's delivery URL, then ImageKit: Get Purge Status to confirm it completed.
Cache purges that spend the quota carefully
ImageKit: Purge Cache clears the CDN and internal cache for one delivery URL per call, asynchronously, and every request counts against the account's monthly purge quota. That makes precision the whole game: purge exactly the URLs that changed after a rename, restore, or re-upload, and poll ImageKit: Get Purge Status for the Completed state before the workflow declares victory. ImageKit: Rename File can request its own purge at rename time through the purgeCache option.
Usage reports that land where the work is
ImageKit: Get Account Usage reads bandwidth, storage, and processing-unit totals for a date range under 90 days, and ImageKit: Get Usage Analytics, a beta API, adds delivery breakdowns: status codes, top 404 assets, cache hit and miss counts, and per-country and per-format splits. A scheduled workflow can write the numbers into a Mattering database and open a task when 404s spike or bandwidth trends toward a limit. Both nodes return totals for the whole range rather than per-day series, so trend lines come from scheduled runs over successive windows.
Example: A new product image arrives: upload it, describe it, tag it, and log the delivery URL
Built on the Automations canvas in a few minutes, or described in plain language to Matter and built for you.
Trigger: an inbound webhook from a form or another app fires with the image's source URL, a product id, and a campaign name.
ImageKit: Upload File from URL passes the source URL to ImageKit, which fetches the file server-side into the right folder and returns its fileId, path, and delivery URL.
ImageKit: Update File Details writes the product id and campaign into custom metadata fields and sets a description on the new file.
ImageKit: Add Tags (Bulk) tags the file so library searches and future automations can find it.
The workflow writes the delivery URL and fileId into a Mattering database row and opens a review task in Mattering Productivity, so a person confirms the asset renders correctly before it ships.
ImageKit MCP questions, answered
What ImageKit operations are supported?
32 nodes: 11 query nodes and 21 action nodes covering media library list and search, file details, update, copy, move, and rename, single and bulk delete, the full version family (list, get, restore, delete non-current), bulk tag add and remove plus AI tag removal, folder create, delete, copy, move, and rename with asynchronous job polling, cache purge with status polling, technical metadata by fileId or by delivery URL, custom metadata field definitions, account usage and delivery analytics, and upload from URL. Deliberately not shipped: the beta V2 upload endpoint (a client-side JWT flow; V1 with Basic auth is the server-side path), saved-extension configuration admin, and the beta account origin and URL-endpoint management APIs.
Does this work with Claude, ChatGPT, or other AI assistants?
Yes. Mattering exposes these nodes over MCP, an open protocol for connecting AI assistants to tools, so any MCP-capable assistant, including Claude and ChatGPT, can connect to your workspace and use them. Matter, the assistant built into the platform, uses the same nodes natively.
ImageKit has an official MCP server. Why use this connector?
ImageKit does publish its own MCP server, hosted at api-mcp.imagekit.io and available on npm as @imagekit/api-mcp, in public preview (beta) at the time of writing, and if all you want is an assistant talking directly to ImageKit, it is a genuine option. This connector earns its place when ImageKit is one step in a larger workflow: the same canvas holds your other connectors and the Mattering platform itself, so an upload can flow into a database row and a review task, a bulk delete can wait behind a human approval step, and a usage sweep can land next to the rest of your work. Credentials live in one place with your other connector secrets, and the same nodes serve visual automations and AI agents alike.
How does authentication work?
With your ImageKit private API key, applied as HTTP Basic auth with the key as the username and an empty password, on both the management and upload hosts. You copy it once from the ImageKit dashboard under Developer options, then API keys. The public key from the same screen authenticates nothing server-side (it exists for client-side upload signatures), and the connector rejects a stored public key with an error telling you to use the private one instead of letting every call fail with a confusing 401.
Can an automation search the media library?
Yes. ImageKit: List Files carries ImageKit's searchQuery parameter, a Lucene-like query language with typed comparisons, so a workflow can ask for things like assets created in the last 7 days over 2 MB by writing the query directly. It composes with the node's type filter (files, file versions, folders, or all), folder scoping, and sorting. Because searchQuery is a language rather than a list of values, it is a field you write, not a dropdown you pick from; the identifier fields on other nodes (fileId, versionId, folder paths, delivery URLs) are the ones that come as pickers filled from the listers.
What are ImageKit's rate limits?
ImageKit rate-limits per endpoint, and the numbers vary by endpoint and by account, so there is no single figure to quote. Each response carries X-RateLimit-Limit, X-RateLimit-Reset (milliseconds to wait before retrying), and X-RateLimit-Interval headers, and exceeding a limit returns HTTP 429, which nodes report on their output rather than silently retrying. The bulk nodes are the pressure valve: tag operations take up to 50 files per call and bulk delete takes up to 100, so batching beats looping.
What happens when an automation deletes something?
It is permanent. ImageKit has no trash and no restore endpoint, which is why five nodes carry a destructive flag: ImageKit: Delete File, ImageKit: Delete Files (Bulk), ImageKit: Delete File Version, ImageKit: Delete Folder, and ImageKit: Delete Custom Metadata Field. Delete folder removes everything inside, and ImageKit does not refuse a non-empty folder. Deleting a custom metadata field permanently retires its name for the whole account. The one built-in guard is on versions: the API refuses to delete a file's current version. The honest pattern is to list first, and put deletes behind a condition or an approval task rather than a bare trigger.
Do I need a paid ImageKit plan?
ImageKit's pricing page lists a free plan that includes the media library and API access, so the connector can be set up and exercised without a paid subscription. Specific allowances such as bandwidth, storage, and monthly purge requests vary by plan and change over time, so check imagekit.io/plans for current numbers. One durable planning fact: cache purge requests count against a monthly quota, so workflows should purge exactly what changed.
Put ImageKit to work inside your workspace
Connect once, then use every node in visual automations and AI agent workflows across the Mattering platform.
All product names, logos, and brands are property of their respective owners and are used for identification purposes only. Use of these names, logos, and brands does not imply endorsement or affiliation. ImageKit is a product of its respective owner; Mattering is an independent platform.