Skip to main content
Glama

Mediagraph CLI

A single binary that exposes the entire Mediagraph API to AI agents and shells. Ships as both a CLI (mediagraph <tool>) and an MCP server (mediagraph serve) — same code path, same auth, same output shape.

About Mediagraph: a digital asset management (DAM) platform for organizing, sharing, and AI-tagging media at scale. Learn more at www.mediagraph.io.

Built for agent workflows: every tool call returns JSON on stdout, errors on stderr with stable codes, and global flags handle the boring stuff (auth, pagination, retries, dry-runs, polling).

Install

npm install -g @mediagraph/cli     # ships the `mediagraph` command

Related MCP server: mcp-openverse

Authentication

Interactive (developer machines)

mediagraph auth login        # opens a browser, completes OAuth, persists tokens
mediagraph auth status       # {authenticated, organization, user, token}

Tokens are stored encrypted at ~/.mediagraph/tokens.enc and refreshed automatically.

Headless (CI, sandboxes, agents)

Use a Personal Access Token. Set both env vars:

export MEDIAGRAPH_PAT="<token>"
export MEDIAGRAPH_ORGANIZATION_ID="<numeric org id>"
mediagraph auth status       # → {authenticated: true, mode: "pat", ...}

Generate a PAT in Mediagraph → Profile → Personal Access Tokens, or via mediagraph create_personal_access_token --name "ci".

CLI usage

mediagraph <tool> [flags]              # invoke any tool, prints JSON
mediagraph <tool> --help               # show flags for a tool
mediagraph list-tools [--brief]        # every tool, JSON
mediagraph search-tools "<query>"      # ranked keyword search over the registry
mediagraph skills [name|list|all]      # focused Markdown recipes for agents
mediagraph skill                       # full bundled agent onboarding guide
mediagraph sync ...                    # continuous folder sync (see below)
mediagraph serve                       # start the MCP server on stdio
mediagraph auth login | logout | status

Tool flags

Every tool's flags are derived from its JSON Schema:

# Flag form
mediagraph search_assets --q "tag_text:nature" --per_page 5
mediagraph create_bulk_job --asset_ids 12,34,56 --tag_names sunset --tag_mode add

# Or pass the whole input as JSON
mediagraph search_assets --json '{"q":"tag_text:nature","per_page":5}'

Type coercion: numbers, booleans (--flag / --no-flag), arrays (comma-separated, repeated, or JSON), objects (JSON only).

Global flags

These work with any tool:

Flag

Purpose

--all

Auto-paginate list_* tools until exhausted

--limit N

Cap total rows when paginating (default 10000)

--dry-run

Print the HTTP call instead of executing — safe preview for mutations

--wait

After a create_*, poll the sibling status tool until terminal

--wait-timeout SEC

Cap --wait duration (default 600)

--envelope

Wrap stdout in {ok, tool, data, meta:{duration_ms, ...}}

--brief

Trim list-tools descriptions to one line

Examples:

# Get all assets matching a query, capped at 500
mediagraph search_assets --q "tag_text:nature" --all --limit 500

# Preview a destructive op
mediagraph delete_asset --id 42 --dry-run

# Block until a bulk job finishes
mediagraph create_bulk_job --asset_ids 1,2,3 --tag_names sunset --tag_mode add --wait

Output contract

  • stdout — JSON only (always parseable). With --envelope, wrapped in {ok, tool, data, meta}.

  • stderr — structured error envelope: {ok: false, code, error, hint?, context?}.

  • exit code — 0 success, 1 runtime/tool/network, 2 argument parse error, 3 auth required.

Stable error codes: AUTH_REQUIRED, BAD_ARGS, UNKNOWN_COMMAND, UNKNOWN_TOOL, NOT_FOUND, RUN_LOCKED, NETWORK, RATE_LIMITED, TOOL_ERROR, CONFIG_ERROR, INTERNAL.

The client honors Retry-After on 429/503 (delta-seconds and HTTP-date forms), caps backoff at 60s, and surfaces X-PAT-Disabled as a structured auth error.

Search syntax

The q parameter on search_assets accepts advanced operators:

Form

Example

Meaning

Term

dog

Match across all searchable fields (cross_fields)

Phrase

"red barn"

Both terms in same field, in order

Exclude

NOT dog, -dog

Exclude matches

Combine

dog AND cat, dog OR cat

Boolean ops

Field

tag_text:nature, filename.keyword:IMG.jpg

Field-scoped

Wildcard

tag_text:part*, tag_text:?artial

* any chars, ? one char

Existence

tag_text:** / NOT tag_text:**

Has any value / has no value

Group

(dog OR cat) AND ext:jpg

Parenthesized

Common fields: tag_text, filename.keyword, description, title, ext, creator_text, copyright, city, state, country.

Continuous folder sync

Mirror a remote storage folder to a local directory (or vice versa) and keep them in sync on a schedule. Resilient to crashes and reboots: every run is idempotent, state persists at ~/.mediagraph/sync/<name>/state.json, and in-flight ops are resumed on the next run.

Three modes: download (pull-only — auto-fetch new assets and new data_version_number bumps; metadata-only changes do NOT re-download), upload (push-only — hash + skip unchanged, mirror folder structure), two-way (conflicts land as <file>.conflict-v<N> next to the local file).

mediagraph sync init my-pull --mode download \
  --storage-folder-id 42 --local-path ~/Pictures/mediagraph \
  --frequency hourly
mediagraph sync run my-pull       # one-shot reconciliation; safe to repeat
mediagraph sync install my-pull   # registers a launchd job (macOS)
mediagraph sync status my-pull    # JSON summary of last run

Harness options (the run command is the same in all cases):

  • OS scheduler (recommended): mediagraph sync install <name> writes a launchd plist on macOS. Survives reboots, captures logs.

  • Coding-agent loop: in Claude Code, /loop 1h mediagraph sync run <name>.

  • Long-running watcher: mediagraph sync watch <name> for low latency without a cron.

  • Manual: just run mediagraph sync run <name> whenever.

Discovering tools

The CLI ships ~157 tools. Don't load them all — search:

mediagraph skills                      # focused guide index
mediagraph skills search               # asset search and inspection recipes
mediagraph search-tools "rename file" --limit 5
mediagraph search-tools "watermark"
mediagraph create_bulk_job --help     # one tool, full schema

Tool groups: assets, search & filters, collections / lightboxes / storage folders, tags & taxonomies, tag imports, rights & sharing, custom meta fields, bulk jobs & uploads, rename presets, meta downloads (background CSV export), workflows, comments, notifications, webhooks, admin (user groups, invites, PATs, organization budget).

Use as an MCP server

For Claude Desktop and other MCP clients:

{
  "mcpServers": {
    "mediagraph": {
      "command": "npx",
      "args": ["@mediagraph/cli", "serve"]
    }
  }
}

Or one-click: download the latest mediagraph-mcp.mcpb bundle from Releases.

The MCP server exposes the same tools and a few resources:

  • mediagraph://asset/{id} — asset details

  • mediagraph://collection/{id} — collection with assets

  • mediagraph://lightbox/{id} — lightbox with assets

  • mediagraph://search?q={query} — search results

It also includes an interactive visual gallery (search_assets_visual) for thumbnail browsing, inline editing, ratings, tagging, and bulk downloads inside Claude Desktop.

Environment

Variable

Default

Purpose

MEDIAGRAPH_PAT

—

Personal Access Token (headless auth)

MEDIAGRAPH_ORGANIZATION_ID

—

Organization id (required with PAT)

MEDIAGRAPH_API_URL

https://api.mediagraph.io

API host

MEDIAGRAPH_OAUTH_URL

https://mediagraph.io

OAuth host

MEDIAGRAPH_CLIENT_ID

(bundled)

OAuth client id (custom apps)

MEDIAGRAPH_CLIENT_SECRET

—

OAuth client secret (confidential clients)

MEDIAGRAPH_REDIRECT_PORT

52584

Local OAuth callback port

MEDIAGRAPH_SYNC_ROOT

~/.mediagraph/sync

Override sync state directory

Agent guides

mediagraph skills prints focused Markdown guides for agents: search, organize, metadata, ingest, bulk jobs/imports, sharing, workflows, and admin. mediagraph skill prints the full bundled SKILL.md onboarding guide.

Security

  • Tokens encrypted at ~/.mediagraph/tokens.enc

  • OAuth uses PKCE for public clients

  • PAT auth uses HTTP Basic + OrganizationId header (matches Mediagraph server-side path)

  • Access tokens auto-refreshed before expiration

  • No secrets logged or exposed in errors

Development

git clone https://github.com/mediagraph-io/mediagraph-mcp.git
cd mediagraph-mcp
npm install
npm run build       # tsup bundle to dist/
npm test            # vitest, ~110 tests
npm run typecheck

Run the local build:

node dist/index.js auth status
node dist/index.js search_assets --q "test" --per_page 5

Test with the MCP inspector:

npx @modelcontextprotocol/inspector node dist/index.js serve

License

MIT — see LICENSE.

Support

History provenance

The MCP server automatically sends X-Mediagraph-Source: mcp; CLI commands, including sync/watch, send X-Mediagraph-Source: cli on authenticated Mediagraph API requests. The header is not sent to S3 or file-download hosts. Both sources appear as Agent in Mediagraph History, while remaining separately filterable.

Use get_asset_event_log with request_source set to mcp, cli, web, api, system, agent (MCP and CLI), or unknown (historical or unattributed records). Source labels describe provenance, not authorization or human approval.

Dedicated super-admin folder duplication

Preview is the default. An active issuing membership, current super-admin role, and explicit bulk_job:write or bulk_jobs:write token scope are required.

mediagraph duplicate_storage_folder_to_collection --source 123 --destination 456 --preview
mediagraph duplicate_storage_folder_to_collection --source 123 --destination 456 --execute --idempotency_key request_20261102_example --wait
mediagraph watch bulk_job <guid>
mediagraph cancel_bulk_job --id <guid>

The server reports resolved targets, live subtree counts, destination conflicts, and dedicated worker readiness. It never deletes destination content. Production needs one separately provisioned admin worker; this command does not provision or scale it. Occupied capacity returns 409; absent/misconfigured workers return 503. Reuse the same key after an uncertain response: retries return the existing job. --dry-run only prints the HTTP request; --preview queries server readiness. --wait requires execute and follows retries until processed, failed, or canceled. Inspect the returned error and counts: processed can include a graceful failure. Do not move/delete source content during a live-tree duplication.

Available Tools

277 tools
accept_inviteA

Accept an invite using its email-link token (public flow — distinct from accept_my_invite which uses the profile-scoped invite list for an authenticated user).

Inputs: token (required).

accept_my_inviteB

Accept a pending org invitation by id.

Inputs: id (required).

add_assets_to_groupA

Add multiple assets to a Collection or Lightbox at once

Inputs: ids (required), asset_group_id (required).

add_assets_to_uploadB

Add assets to an upload session

Inputs: guid (required), asset_ids (required).

add_asset_to_collectionC

Add an asset to a collection

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

add_asset_to_lightboxB

Add an asset to a lightbox

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

add_asset_versionA

Initiate an upload of a NEW version of an existing asset. Returns a signed S3 URL; PUT the file there to complete. For end-to-end uploads from disk, prefer upload_file with the asset id.

Inputs: id (required), filename (required), file_size (required), content_type (required).

add_organization_cai_budgetB

Super-admin: send a Stripe invoice for a CAI budget top-up

Inputs: id (required), amount, description.

add_tags_to_assetC

Add tags to an asset

Inputs: id (required), tags (required).

add_tag_to_taxonomyB

Add an existing tag to a taxonomy as a taxonomy_tag.

Inputs: id (required), taxonomy_id (required).

agree_to_access_requestB

Guest: record agreement to terms / NDA on an access request.

Inputs: id (required).

apply_lightbox_membership_assetsA

Push a lightbox membership's pinned assets out to all members (creates per-member copies). Used to broadcast curated picks to a shared lightbox.

Inputs: asset_ids (required), asset_group_membership_id (required).

approve_workflow_stepB

Approve all selected assets in a workflow step, moving them to the next step.

Inputs: id (required), asset_ids (required).

approve_workflow_step_picksA

Approve a curated subset (picks) within a workflow step. Same shape as approve_workflow_step but only the chosen assets advance.

Inputs: id (required), asset_ids (required).

associate_tagging_with_faceA

Associate an existing tagging with a Rekognition face id (link tagging → detected face crop).

Inputs: id (required), face_id (required).

auto_tag_assetA

Run Rekognition / Vision auto-tagging on a single asset. Existing auto-tags are preserved; new ones are appended.

Inputs: id (required).

block_asset_faceA

Block a detected face crop on an asset (creates a "Blocked Face" tag and excludes from future matching).

Inputs: id (required), face_id (required).

bulk_add_tags_to_assetsB

Add the same tag names to many assets at once.

Inputs: asset_ids (required), tag_names (required).

bulk_delete_tagsA

Delete many tags by id in a single call.

Inputs: ids (required).

bulk_download_assetsA

Get a download URL for multiple assets (returns a ZIP file)

Inputs: asset_ids (required), via, size, skip_meta, +1 more.

bulk_edit_assetsA

Update fields on many assets in a single call. Pass an updates object with the same field names as update_asset (title, description, alt_text, caption, credit, copyright, etc.).

Inputs: updates (required), asset_ids (required).

bulk_find_auto_tagsA

Find multiple auto tags by their names at once

Inputs: tag_names (required).

bulk_find_tagsA

Find or stub many tags by name in a single call. Returns existing tags where matched, otherwise unsaved Tag-shaped records the agent can persist.

Inputs: names (required).

bulk_find_taxonomy_tagsA

Find or stub many taxonomy_tags by name in a single call (top-level — searches across taxonomies).

Inputs: names (required).

bulk_remove_tags_from_assetsA

Remove the same tag names from many assets at once.

Inputs: asset_ids (required), tag_names (required).

bulk_set_asset_creator_tagA

Set (or clear with null) the creator tag on many assets in one call.

Inputs: asset_ids (required), creator_tag_id.

bulk_set_asset_rights_packageA

Set (or clear with null) the rights package on many assets in one call.

Inputs: asset_ids (required), rights_package_id.

bulk_update_tagsC

Apply a single change to many tags (set list, attach/detach taxonomy).

Inputs: tag_ids (required), list, add_taxonomy, remove_taxonomy.

cancel_bulk_jobB

Cancel a running bulk job

Inputs: id (required).

can_uploadA

Check if uploads are allowed (storage quota)

Inputs: no named parameters.

check_invite_emailA

Check whether a given email is a valid recipient for a new invite (already has account, already in org, etc.).

Inputs: email (required).

check_tag_nameA

Async uniqueness check for a tag name (e.g., for artwork inventory numbers). Returns { exists: boolean }.

Inputs: name (required).

clear_asset_nsfwA

Mark an NSFW detection as a false positive on an asset; clears the moderation flag and re-indexes.

Inputs: id (required).

create_access_requestA

Create a draft access request (pre-submit). Use submit_access_request to send it.

Inputs: purpose, asset_id, custom_meta, asset_group_id, +1 more.

create_asset_group_inviteA

Invite a user (by email) or existing membership to a collection / lightbox / storage folder.

Inputs: asset_group_id (required), role, email, message, +1 more.

create_bulk_jobA

Create a bulk job for batch operations on assets. Supports multiple operation types:

  • Tag management: use tag_names + tag_mode (add/remove/replace)

  • Metadata updates: use description + description_mode (set/append/prepend), rating, rights_package_id

  • Organization: use add_asset_group_id + add_asset_group_type (Collection/Lightbox/StorageFolder)

  • AI processing: use run_custom_meta_field_ids + cmf_overwrite_mode (skip/overwrite)

  • Bulk actions: use destroy_all, restore_all, or generate_alt_text

Inputs: asset_ids (required), rating, tag_mode, tag_names, +22 more.

create_collectionC

Create a new collection

Inputs: name (required), parent_id, description.

create_commentA

Create a new comment on a Lightbox or Collection. Supports markdown and @mentions.

Inputs: id (required), text (required), type (required).

create_contributionB

Create a new contribution portal (named upload link tied to a collection / lightbox / folder).

Inputs: name (required), enabled, message, require_login, +2 more.

create_creator_tagC

Create a new creator tag

Inputs: name (required).

create_crop_presetC

Create a crop preset

Inputs: name (required), width (required), height (required).

create_custom_meta_fieldC

Create a custom metadata field

Inputs: name (required), field_type (required), options, required, +5 more.

create_downloadC

Create a batch download for multiple assets

Inputs: asset_ids (required), size.

create_filter_groupC

Create a new filter group with saved filter configurations

Inputs: name (required), filter_order.

create_inviteB

Invite a user to the organization

Inputs: email (required), role_level (required), note.

create_lightboxC

Create a new lightbox

Inputs: name (required), parent_id, description.

create_meta_downloadA

Kick off a background metadata CSV export. Returns { guid } to poll status.

Inputs: asset_ids (required), columns, send_email, column_preset.

create_personal_access_tokenC

Create a personal access token

Inputs: name (required), scopes.

create_rename_presetC

Create a rename preset

Inputs: name (required), enabled, position, template.

create_rights_packageC

Create a new rights package

Inputs: name (required), rights_class (required), expires, expires_at, +1 more.

create_search_queryA

Save a new search query. The sql field should contain an Elasticsearch SQL WHERE clause.

Inputs: sql (required), name (required), description.

create_shareC

Create a share (transfer assets / a group to a user). See Mediagraph share docs for the body fields supported by your org.

Inputs: email, message, asset_ids, expires_at, +1 more.

create_storage_folderD

Create a new storage folder

Inputs: name (required), parent_id, description.

create_tagA

Create a new tag. Supports the full enrichment surface (description, sub_type, link, event fields, artwork fields, external-system identifiers).

Inputs: name (required), sku, gtin, link, +34 more.

create_tag_importB

Create a tag-import job. file is the uploaded CSV/XLS file reference (S3 key or upload id).

Inputs: file (required), note, columns, name_column.

create_taxonomyC

Create a new taxonomy

Inputs: name (required), description.

create_taxonomy_tagC

Create a tag within a taxonomy

Inputs: name (required), taxonomy_id (required), parent_id.

create_upload_sessionA

Create a long-lived upload session that you can append files to over multiple upload_file / upload_files calls.

Use this when batch-uploading many files from a script or agent loop, when you want them grouped under one upload in the Mediagraph UI, or when you need to resume after a crash.

Returns the session guid plus aws_key/bucket (used internally for direct-to-S3 multipart). Call set_upload_done with the returned id when the batch is complete.

Inputs: name, note, contribution_id, default_rights_package_id.

create_user_groupC

Create a user group

Inputs: name (required), description.

create_webhookB

Create a webhook to receive event notifications

Inputs: url (required), name (required), note, trash, +5 more.

create_workflowC

Create a new workflow.

Inputs: name (required), enabled, description.

create_workflow_stepB

Create a workflow step (typically attached to a workflow + asset_group).

Inputs: workflow_id (required), name, position, asset_group_id, +1 more.

delete_access_grantC

Delete (revoke) an access grant.

Inputs: id (required).

delete_access_requestB

Delete an access request.

Inputs: id (required).

delete_assetA

Delete (trash) an asset

Inputs: id (required).

delete_asset_group_inviteB

Cancel/revoke an asset group invite.

Inputs: id (required).

delete_auto_tagC

Delete/dismiss an auto tag

Inputs: id (required).

delete_collectionC

Delete a collection

Inputs: id (required).

delete_commentA

Delete a comment. Only the comment author can delete their own comments.

Inputs: id (required).

delete_contributionC

Delete a contribution portal.

Inputs: id (required).

delete_filter_groupB

Delete a filter group

Inputs: id (required).

delete_lightboxB

Delete a lightbox

Inputs: id (required).

delete_personal_access_tokenB

Delete a personal access token

Inputs: id (required).

delete_published_imageA

Delete a single PublishedImage row. Auto-cleans the parent PublishedAsset when the last image is removed.

Inputs: id (required).

delete_rename_presetB

Delete a rename preset

Inputs: id (required).

delete_search_queryB

Delete a saved search query

Inputs: id (required).

delete_shareB

Revoke / delete a share by id.

Inputs: id (required).

delete_tagB

Delete a tag

Inputs: id (required).

delete_taggingA

Remove a tagging (untag an asset)

Inputs: id (required).

delete_tag_importB

Delete a tag-import job

Inputs: id (required).

delete_taxonomyA

Delete a taxonomy. Tags inside it are detached, not deleted.

Inputs: id (required).

delete_taxonomy_tagC

Delete a tag from a taxonomy.

Inputs: id (required), taxonomy_id (required).

delete_user_groupA

Delete a user group. Members are not deleted.

Inputs: id (required).

delete_webhookB

Delete a webhook

Inputs: id (required).

delete_workflowA

Delete a workflow. In-flight workflow_steps may need to be cancelled separately.

Inputs: id (required).

delete_workflow_stepB

Delete a workflow step.

Inputs: id (required).

detect_video_facesA

Trigger face detection for an existing video asset (for videos uploaded before video face tagging shipped).

Inputs: id (required).

disable_my_otpA

Disable TOTP 2FA on the current user account.

Inputs: no named parameters.

disable_personal_access_tokenA

Super-admin: disable a PAT (requests respond with X-PAT-Disabled header)

Inputs: id (required).

disassociate_tagging_with_faceA

Remove the face-crop association from a tagging.

Inputs: id (required).

duplicate_storage_folder_to_collectionA

Super-admin: preview or submit a folder subtree duplication into a Collection using reserved admin worker capacity. Defaults to a server preview. Execute requires a stable idempotency key; never deletes destination content.

Inputs: source (required), destination (required), execute, preview, +2 more.

enable_my_otpA

Enable TOTP 2FA on the current user account by confirming a 6-digit code.

Inputs: otp_attempt (required).

enable_personal_access_tokenA

Super-admin: re-enable a previously disabled PAT

Inputs: id (required).

export_custom_meta_fieldsC

Bulk export custom meta fields by ID

Inputs: ids (required).

extend_organization_trialA

Admin: extend a trialing/past_due/canceled subscription

Inputs: id (required), days, until.

finalize_access_requestA

Admin: finalize a submitted access request — approves and grants access.

Inputs: id (required).

find_access_requestA

Find an access request by guid (used in guest-link resolution).

Inputs: guid (required).

find_contributionC

Find a contribution by slug.

Inputs: slug (required).

find_inviteA

Look up an invite by token (for the public invite-acceptance flow).

Inputs: token (required).

find_membershipB

Find a single membership in the current org by username OR user_id.

Inputs: user_id, username.

find_organizationA

Find an organization by slug. Useful when you have a custom-domain URL or know the slug but not the id.

Inputs: slug (required).

generate_asset_alt_textA

Generate accessibility alt text for an asset using AI; saves to the alt_text field.

Inputs: id (required).

generate_urlA

Generate a direct deep-link URL to a Mediagraph entity (asset, collection, lightbox, storage folder, tag, creator tag, share link, or the explore root).

Two host modes:

Path patterns: asset → /explore#/assets/{guid} (hash route) collection → /explore/collections/{slug} lightbox → /explore/projects/{id}-{slug} storage_folder → /explore/folders/{slug} tag, creator_tag → /explore/tags/{id}-{name} share_link → /share-links/{share_code}

Identifier rules:

  • Pass whichever identifier you already have (guid, slug, id+name, etc.); the tool fetches the entity if needed to derive the rest.

  • For assets, only guid is needed.

  • For collections / storage folders, slug works directly.

  • For lightboxes, the API returns a composite "slug" of the form "{id}-{name}" — pass it as slug.

  • For tags, pass id (and optionally name for a prettier URL).

Override host with --host (e.g., point at staging) or --base_host (just the fallback).

Inputs: type (required), id, guid, host, +5 more.

get_access_requestC

Get access request details

Inputs: id (required).

get_access_requests_treeA

Hierarchical tree view of access requests by asset group.

Inputs: no named parameters.

get_assetC

Get detailed information about a specific asset

Inputs: id (required), include_meta, include_renditions.

get_asset_added_byA

Find which user added a given asset to a given asset_group (collection / lightbox / folder).

Inputs: id (required), asset_group_id (required).

get_asset_auto_tagsB

Get AI-generated auto tags for an asset

Inputs: id (required).

get_asset_contentB

Get extracted text content for a document asset (PDF/DOCX/etc.).

Inputs: id (required).

get_asset_countsC

Get asset counts with optional filters

Inputs: tags, collection_id, storage_folder_id.

get_asset_downloadB

Get a download URL for an asset

Inputs: id (required), size, watermarked, version_number.

get_asset_event_logB

Audit trail for an asset: every version + who did what, paginated.

Inputs: id (required), page, per_page, request_source.

get_asset_face_taggingsB

Get face taggings for an asset

Inputs: id (required).

get_asset_group_inviteB

Get an asset group invite by id.

Inputs: id (required).

get_asset_metaA

Get extracted EXIF / IPTC / XMP / file metadata for an asset.

Inputs: id (required).

get_asset_ocr_contentB

Get OCR-extracted text from an image asset.

Inputs: id (required).

get_assets_updated_since_last_syncA

Sync helper: returns asset ids that changed since last_sync_at (or since the server-tracked last_external_sync_at if omitted). Useful for export/mirror jobs.

Inputs: any_user, created_via, last_sync_at.

get_asset_versionsB

Get version history for an asset

Inputs: asset_id (required).

get_auto_tagC

Get auto tag details

Inputs: id (required).

get_available_invite_role_levelsA

Return the list of role_level values that the current user is allowed to grant in an invite. Helps prevent BAD_ARGS at create time.

Inputs: no named parameters.

get_bulk_jobB

Get bulk job details and status

Inputs: id (required).

get_bulk_job_queue_positionB

Get queue position for a bulk job

Inputs: id (required).

get_collectionC

Get collection details

Inputs: id (required).

get_collections_treeA

Get collections hierarchy as a tree

Inputs: no named parameters.

get_contributionC

Get contribution details

Inputs: id (required).

get_custom_meta_fieldB

Get custom meta field details

Inputs: id (required).

get_downloadC

Get download status and URL

Inputs: token (required).

get_filter_groupC

Get filter group details

Inputs: id (required).

get_lightboxB

Get lightbox details

Inputs: id (required).

get_lightboxes_treeB

Get lightboxes hierarchy as a tree

Inputs: no named parameters.

get_membershipB

Get membership details by ID

Inputs: id (required).

get_meta_download_columnsA

Get the column catalog for metadata exports (grouped + IPTC + custom meta fields), plus the default basic set

Inputs: no named parameters.

get_meta_importC

Get metadata import job details

Inputs: id (required).

get_my_otp_uriA

Get the otpauth:// URI for setting up TOTP 2FA on the current user account (encode in a QR code).

Inputs: no named parameters.

get_notification_countA

Get unread notification count

Inputs: no named parameters.

get_organizationA

Get details about an organization by ID

Inputs: id (required).

get_organization_abilitiesA

Get the current user's role-derived abilities (manage Asset, view_details Tag, etc.) in an organization. Pair with INSUFFICIENT_SCOPE errors so you can distinguish role denial from missing token scope.

Inputs: id (required).

get_pending_membership_requests_countA

Count of pending membership requests (for badging admin dashboards).

Inputs: no named parameters.

get_recent_tag_eventsA

Top 10 most recent tag activity events (no pagination).

Inputs: no named parameters.

get_rename_presetA

Get a rename preset

Inputs: id (required).

get_rights_packageC

Get rights package details

Inputs: id (required).

get_search_queryC

Get search query details

Inputs: id (required).

get_selected_assetsA

Fetch full asset records for an explicit ID list in one call. Use after search_assets returned a set of IDs and you want full attributes without N round-trips.

Inputs: ids (required), aggregates_only.

get_shareB

Get a share by id.

Inputs: id (required).

get_share_assetsA

List the assets included in a share.

Inputs: id (required), page, per_page.

get_share_htmlA

Render the HTML email body that would be sent for this share (preview).

Inputs: id (required).

get_share_statusA

Lightweight status poll for a share (aasm_state, progress, code, url, direct_link)

Inputs: id (required).

get_storage_folderB

Get storage folder details

Inputs: id (required).

get_storage_folders_treeA

Get storage folders hierarchy as a tree

Inputs: no named parameters.

get_tagC

Get tag details

Inputs: id (required).

get_tag_associated_facesA

List the face crops currently associated with a person tag (across the org).

Inputs: id (required).

get_tag_eventsB

List recent tag activity events for the org. Optionally filter by year/month.

Inputs: page, year, month, per_page.

get_taggingB

Get details of a specific tagging (tag-to-asset relationship)

Inputs: id (required).

get_tag_importC

Get a tag-import job

Inputs: id (required).

get_tag_import_tagsA

List tags created/updated by a tag-import job

Inputs: id (required), page, per_page.

get_taxonomyC

Get taxonomy details

Inputs: id (required).

get_taxonomy_tags_treeA

Hierarchical tree view of all taxonomy_tags within a taxonomy (parent → children).

Inputs: taxonomy_id (required).

get_taxonomy_tags_visible_asset_countsA

Count assets visible-to-current-user under each taxonomy_tag id (for displaying counts in a tree view).

Inputs: taxonomy_id (required), taxonomy_tag_ids (required).

get_trashed_assetsC

Get trashed assets

Inputs: page, per_page.

get_user_groupA

Get a user group by id (members + permissions).

Inputs: id (required).

get_webhookB

Get webhook details

Inputs: id (required).

get_webhook_logsC

Get webhook delivery logs

Inputs: id (required), page, per_page.

get_workflowC

Get workflow details

Inputs: id (required).

get_workflow_stepA

Get a workflow step by id.

Inputs: id (required).

grant_organization_cai_budgetC

Super-admin: grant free CAI budget to an organization

Inputs: id (required), amount, description.

ignore_asset_face_toggleA

Toggle the per-asset "ignore" state on a detected face id. Useful for hiding low-confidence detections without blocking the face globally.

Inputs: id (required), face_id (required).

ignore_asset_unidentified_facesA

Hide all unidentified (unmatched) face crops on an asset.

Inputs: id (required).

list_access_grantsA

List access grants (the records produced when an access request is finalized).

Inputs: page, per_page.

list_access_requestsC

List access requests and grants

Inputs: q, page, type, per_page, +1 more.

list_asset_group_invitesB

List pending and accepted invitations to collections, lightboxes, and storage folders.

Inputs: page, per_page.

list_auto_tagsB

List AI-generated auto tags

Inputs: q, page, per_page.

list_bulk_jobsC

List bulk jobs

Inputs: page, per_page.

list_collectionsC

List collections in the organization

Inputs: q, page, per_page, parent_id.

list_commentsA

List comments on a Lightbox or Collection

Inputs: id (required), type (required), page, per_page.

list_contributionsA

List contribution portals (upload links). Use contribution_id with upload_file/upload_files to upload to a specific storage folder or lightbox.

Inputs: q, page, per_page.

list_creator_tagsC

List creator/photographer tags

Inputs: q, page, per_page.

list_crop_presetsC

List crop presets

Inputs: page, per_page.

list_custom_meta_fieldsC

List custom metadata fields

Inputs: q, page, per_page.

list_filter_groupsC

List saved filter groups

Inputs: page, per_page.

list_group_contributionsB

List contributions tied to a collection / lightbox / folder.

Inputs: no named parameters.

list_ingestionsC

List ingestion jobs

Inputs: page, per_page.

list_invitesC

List pending invites

Inputs: q, page, per_page.

list_lightbox_contributionsB

List contributions tied to lightboxes.

Inputs: no named parameters.

list_lightboxesB

List lightboxes in the organization

Inputs: page, per_page, parent_id.

list_membership_requestsA

List pending requests from users asking to join the current org.

Inputs: page, per_page.

list_membershipsC

List organization memberships

Inputs: page, per_page.

list_meta_downloadsB

List background metadata-export jobs

Inputs: page, dates, user_id, per_page.

list_meta_importsC

List metadata import jobs

Inputs: q, page, per_page.

list_my_invitesA

List pending org invitations addressed to the current user.

Inputs: no named parameters.

list_my_organizationsA

List every organization the current user belongs to (across orgs). Useful for multi-tenant agents picking which org to operate in.

Inputs: no named parameters.

list_notificationsC

List notifications

Inputs: page, per_page.

list_personal_access_tokensA

List personal access tokens

Inputs: page, per_page.

list_rename_presetsB

List rename presets

Inputs: page, enabled, per_page.

list_rights_packagesB

List rights packages for managing asset usage rights

Inputs: page, per_page.

list_search_queriesB

List saved search queries

Inputs: page, per_page.

list_sharesA

List shares (one-off transfers of an asset/group to a user, distinct from public share_links).

Inputs: page, per_page.

list_storage_foldersC

List storage folders

Inputs: page, per_page, parent_id.

list_tag_importsB

List tag-import jobs

Inputs: page, per_page.

list_tagsC

List tags in the organization

Inputs: q, page, per_page, tag_import_id.

list_taxonomiesB

List taxonomies (controlled vocabularies)

Inputs: page, per_page.

list_taxonomy_tagsB

List tags within a taxonomy

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

list_uploadsC

List upload sessions

Inputs: page, per_page.

list_user_groupsC

List user groups

Inputs: q, page, per_page.

list_webhooksB

List webhooks

Inputs: q, page, per_page.

list_workflowsC

List workflows

Inputs: page, per_page.

list_workflow_stepsA

List workflow steps (the user-facing approval queue).

Inputs: page, per_page.

mark_organization_cai_invoice_paidB

Super-admin: mark an open CAI invoice as paid out-of-band

Inputs: id (required).

merge_tagsA

Merge one tag into another. With set_synonym=true, the source tag is preserved as a synonym of the target instead of being deleted.

Inputs: id (required), target_tag_id (required), set_synonym.

preview_rename_bulk_jobA

Preview the filenames a rename bulk job will produce, before submitting it.

Inputs: asset_ids (required), rename_preset_id (required), custom_text, global_start, +2 more.

reauthorizeA

Re-run the OAuth authorization flow. Use this to switch to a different Mediagraph organization or re-authenticate.

Inputs: no named parameters.

remove_asset_auto_tagB

Dismiss a specific auto-tag from this asset (does not delete the auto-tag globally).

Inputs: id (required), auto_tag_id (required).

remove_assets_from_groupA

Remove many assets from a collection / lightbox / storage folder at once.

Inputs: asset_ids (required), asset_group_id (required).

remove_lightbox_membership_assetsB

Remove pinned-assets from a lightbox membership (counterpart to apply).

Inputs: asset_ids (required), asset_group_membership_id (required).

remove_tag_face_creator_tagB

Unlink the creator-tag association from a person tag.

Inputs: id (required).

remove_tag_face_membershipC

Remove the user-membership association from a person tag.

Inputs: id (required).

remove_tag_taxonomiesA

Detach a tag from all taxonomies it belongs to.

Inputs: id (required).

reorder_rename_presetsB

Reorder rename presets by moving one from oldIndex to newIndex

Inputs: newIndex (required), oldIndex (required).

resend_inviteB

Resend an invite email

Inputs: id (required).

reset_tag_faceA

Clear face-tagging state on a person tag and re-enqueue Rekognition indexing.

Inputs: id (required).

restore_assetA

Restore a trashed asset (undo delete_asset).

Inputs: id (required).

revert_assetB

Revert an asset to a previous version

Inputs: id (required), version (required).

revoke_access_requestB

Admin: revoke a previously granted access request.

Inputs: id (required).

run_asset_aiA

Invoke an AI-enabled custom meta field action on an asset (e.g., LLM-driven extraction, classification, or description).

Inputs: id (required), custom_meta_field_id (required).

search_asset_facesB

Run face search on an asset using the org-wide face index; matches detected faces to indexed person tags. Reindexes the asset on success.

Inputs: id (required).

search_assetsA

Search for assets using filters and advanced query operators.

ADVANCED SEARCH QUERY SYNTAX (for the 'q' parameter):

  • Basic: Just type a term to search all fields (e.g., "dog")

  • Exclude: Use NOT or minus to exclude (e.g., "NOT dog" or "-dog")

  • Combine: Use AND, OR, NOT (e.g., "dog AND cat", "dog OR cat", "dog NOT cat")

  • Field search: Use field:value syntax (e.g., "tag_text:nature", "filename.keyword:IMG_1234.jpg")

  • Wildcards: Use * (zero or more chars) or ? (single char) (e.g., "tag_text:part*", "tag_text:?artial")

  • Existence: Use field:** to find assets with any value, NOT field:** for empty (e.g., "NOT tag_text:**" finds untagged assets)

  • Complex: Use parentheses for grouping (e.g., "(dog OR cat) AND ext:jpg")

NOTE on multi-word queries: the API uses Elasticsearch cross_fields, so a multi-word query like "red barn" can match if "red" appears in one field and "barn" appears in another. Quote phrases ("red barn") to require both terms in the same field.

Sort: pass either 'order' or its alias 'direction' (asc/desc). Results have an implicit id:asc tiebreaker (except when using a custom sort).

COMMON SEARCH FIELDS:

  • tag_text: Keywords/tags

  • filename.keyword: Exact filename

  • description: Asset description

  • title: Asset title

  • ext: File extension

  • creator_text: Creator/photographer name

  • copyright: Copyright text

  • city, state, country: Location fields

Inputs: q, gps, ids, exts, +16 more.

search_assets_visualA

Search for assets and display results in an interactive visual gallery.

This tool provides a rich visual interface for browsing search results with:

  • Thumbnail grid with hover previews

  • Click to view full asset details

  • Inline editing of metadata

  • Rating, tagging, and download options

  • Pagination controls

Use this when the user wants to visually browse or explore assets.

Inputs: q, gps, ids, exts, +13 more.

search_membershipsA

Search memberships within a comment context (collection / lightbox) — used for assignee pickers and @-mention lookups in commenting flows.

Inputs: q, page, per_page, commentable_id, +1 more.

set_access_request_custom_metaB

Set a custom meta field value on an access request (mirrors set_asset_custom_meta).

Inputs: id (required), custom_meta_field_id (required), text, value, +2 more.

set_asset_custom_metaA

Write to a custom meta field on an asset. The field's shape determines which value param to pass:

  • free (free-text): pass value (or text)

  • select (single-pick): pass custom_meta_value_id

  • multi (multi-pick): pass custom_meta_value_ids (array)

Pass none of value/text/*_id to clear the field. The asset is reindexed on success.

Inputs: id (required), custom_meta_field_id (required), text, value, +2 more.

set_asset_preview_image_from_timeA

For a video asset: set the poster/preview image from the frame at seconds into the video.

Inputs: id (required), seconds (required).

set_main_face_for_taggingA

Promote a tagging to the canonical face for its tag. Used after tag_asset_face to pick which crop represents the person.

Inputs: id (required).

set_tag_face_creator_tagA

Link a person tag to a creator tag by name. Photos created by that creator gain the linked person tag automatically.

Inputs: id (required), name (required).

set_tag_face_membershipA

Associate a person tag with a user (by email). The user becomes the canonical "face" for the tag — useful for faceless tags that need to point to a real person.

Inputs: id (required), email (required).

set_upload_doneA

Finalize an upload session, marking it as complete. Triggers any post-upload hooks (notifications, contribution acceptance, etc.). Call this after the last upload_file/upload_files in a batch you opened with create_upload_session.

Inputs: id (required).

slice_new_assetA

Slice a video asset between start and end (seconds) and queue the result as a brand-NEW asset (optionally added to a lightbox).

Inputs: id (required), end (required), start (required), lightbox_id.

slice_new_asset_versionA

Slice a video asset between start and end (seconds) and queue the result as a NEW VERSION of the same asset. Async — poll the asset.

Inputs: id (required), end (required), start (required).

start_tag_importA

Start processing a tag-import job once it is in the analyzed state

Inputs: id (required).

submit_access_requestD

Submit an access request

Inputs: id (required).

tag_asset_faceA

Manually tag a detected face crop on an image asset and index it into Rekognition for org-wide face matching.

Workflow for "upload a headshot for a person tag":

  1. Upload the headshot via upload_file (optionally with the person tag attached).

  2. Call get_asset_face_taggings to get the face_id of the detected face crop.

  3. Call tag_asset_face with the person tag's id (or a new name) + that face_id.

After indexing, future uploads automatically run face matching against this person.

Inputs: id (required), face_id (required), name, tag_id.

tag_video_faceC

Manually tag a face track in a video; indexes the cropped frame into Rekognition.

Inputs: id (required), person_index (required), name, tag_id.

transfer_lightbox_ownershipA

Transfer ownership of a lightbox to another user (by user id).

Inputs: id (required), user_id (required).

update_access_requestC

Update an in-progress access request.

Inputs: id (required), purpose, custom_meta.

update_assetC

Update asset metadata

Inputs: id (required), city, notes, state, +9 more.

update_asset_descriptionA

Patch only the description field on an asset (lighter than update_asset; does not touch other fields).

Inputs: id (required), description (required).

update_asset_group_inviteB

Update an asset group invite (e.g. change role).

Inputs: id (required), role, message.

update_collectionD

Update a collection

Inputs: id (required), name, description.

update_commentA

Update a comment. Only the comment author can update their own comments.

Inputs: id (required), text (required).

update_contributionC

Update a contribution portal.

Inputs: id (required), name, enabled, message, +2 more.

update_filter_groupC

Update a filter group

Inputs: id (required), name, filter_order.

update_filter_group_visibilityB

Update the visibility of a specific filter within a filter group

Inputs: id (required), name (required), type (required), visible (required).

update_inviteB

Update an invite (change role or note)

Inputs: id (required), note, role_level.

update_lightboxC

Update a lightbox

Inputs: id (required), name, description.

update_membershipD

Update a membership

Inputs: id (required), role.

update_membership_statusA

Update the AASM status of a membership (e.g. activate, suspend). Different from update_membership which patches role_level / preferences.

Inputs: id (required), status (required).

update_meta_downloadA

Toggle the send_email flag on an in-progress metadata export

Inputs: guid (required), send_email (required).

update_rename_presetC

Update a rename preset

Inputs: id (required), name, enabled, position, +1 more.

update_search_queryA

Update a saved search query name or description. Note: The SQL query cannot be changed after creation.

Inputs: id (required), name, description.

update_tagB

Update a tag — accepts every enrichment field (description, sub_type, link, event fields, artwork fields, external-system links, synonym graph).

Inputs: id (required), sku, gtin, link, +37 more.

update_tag_importC

Update a tag-import job

Inputs: id (required), note, columns, name_column.

update_tag_import_mappingC

Set the column mapping for a tag-import job

Inputs: id (required), column (required).

update_taxonomyC

Update a taxonomy (name, description, etc.).

Inputs: id (required), name, description.

update_taxonomy_tagC

Update a tag inside a taxonomy.

Inputs: id (required), taxonomy_id (required), name, parent_id.

update_user_groupC

Update a user group (name, description, etc.).

Inputs: id (required), name, description.

update_workflowD

Update a workflow.

Inputs: id (required), name, enabled, description.

update_workflow_stepC

Update a workflow step.

Inputs: id (required), name, position, preserve_subfolders.

upload_asset_transcriptB

Upload a closed-caption / transcript text for a video asset (e.g. WebVTT or plain text).

Inputs: id (required), transcript (required).

upload_fileA

Upload a file to Mediagraph. Two body modes (file_path or file_data) and three session modes:

Body modes:

  1. Local file: Provide file_path for files on the user's local filesystem

  2. Direct upload: Provide file_data (base64-encoded) with filename for files from other sources

Session modes (mutually exclusive):

  • Default: a fresh one-shot upload session is created and finalized for this single file.

  • upload_guid: append to an existing session created via create_upload_session. The session is NOT finalized; call set_upload_done when your batch is complete.

  • contribution_id: upload via a contribution's configured destination (storage folder / lightbox).

Files >16 MiB automatically use S3 multipart upload (parallel parts, retry per part); smaller files go through a single signed PUT.

Inputs: filename, file_data, file_path, upload_guid, +1 more.

upload_filesA

Upload multiple files from the local filesystem in one operation.

Session behavior:

  • Default: creates one fresh session, uploads all files into it, finalizes it.

  • upload_guid: appends to an existing session; does NOT finalize (caller's job).

  • contribution_id: routes the new session through a contribution.

Files >16 MiB use S3 multipart automatically.

Inputs: file_paths (required), upload_guid, contribution_id.

whoamiA

Get information about the currently authenticated user and organization

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 277 tools

    Disambiguation2/5

    With 277 tools, many operations are adjacent or overlapping: add_tags_to_asset vs bulk_add_tags_to_assets vs create_bulk_job tag mode; update_asset vs update_asset_description vs bulk_edit_assets; and numerous list/find/search variants across tags, faces, shares, access requests, and contributions. Descriptions help, but the sheer density of near-duplicate tools makes misselection likely.

    Naming Consistency4/5

    Overwhelmingly consistent snake_case with predictable verb_noun families such as list_*, get_*, create_*, update_*, delete_*, and bulk_*. A few exceptions like whoami, reauthorize, and compound verbs such as apply_lightbox_membership_assets are readable and do not seriously undermine the pattern.

    Tool Count1/5

    277 tools is far beyond an appropriate scope, even for a full DAM platform, and many single/bulk/resource-specific variants could be consolidated. This is an extreme count mismatch under the rubric.

    Completeness4/5

    The surface covers core DAM lifecycle areas broadly: assets, collections, lightboxes, folders, tags/taxonomies, uploads, AI/face tagging, workflows, sharing, access requests, memberships, webhooks, and organization management. Minor gaps remain, such as storage-folder update/delete and notification read actions, but most workflows have a path.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Exposes the inmydata agents SDK as an MCP server, enabling AI agents to access inmydata's powerful data querying capabilities through a standardized interface.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for searching and retrieving Creative-Commons-licensed images and audio from Openverse. Enables AI agents to query open media content.
      204 npm
      MIT