frameio-mcp

A local stdio MCP server over the Frame.io v4 API, built with FastMCP on top of the official frameio Python SDK. It lets an MCP client (Claude Desktop, Claude Code, etc.) browse workspaces/projects/folders, upload footage, leave timestamped review comments, and create share links.

Most people don't need this README. To use it in Claude Code, install the plugin from the marketplace (see the repo root README) and run the frameio-setup skill. This document covers running the server standalone (without the plugin) for development, and the full tool list. Dev uv commands below assume you're in this directory (plugins/frameio-mcp/).

How auth works

Frame.io uses Adobe IMS OAuth. This server uses an OAuth Single-Page App (SPA) credential — a public client (no secret) with PKCE — and stores the resulting tokens in ~/.frameio-mcp/tokens.json (mode 0600). Access tokens auto-refresh via the refresh token granted by the offline_access scope, so you log in rarely.

One-time setup in the Adobe Developer Console

1. In your Frame.io project, add an OAuth Single Page App credential.
2. Scopes: openid, profile, email, offline_access, additional_info.roles.
3. Redirect URI: https://localhost:8723/callback (must match exactly).
4. Copy the credential's Client ID.

Install & log in

uv sync                                  # install deps
uv run frameio-mcp login --client-id <YOUR_SPA_CLIENT_ID>

A browser opens for Adobe sign-in. Because Adobe requires HTTPS even on localhost, the temporary callback server uses a self-signed cert — your browser will warn "connection is not private." Click Advanced → Proceed to localhost. That's expected and only happens at login.

Check state anytime:

uv run frameio-mcp status
uv run frameio-mcp logout   # remove tokens

Run the server

uv run frameio-mcp serve     # stdio MCP server

Claude Desktop / Claude Code config

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "frame.io": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/frameio-mcp/plugins/frameio-mcp", "frameio-mcp", "serve"]
    }
  }
}

The Client ID is read from ~/.frameio-mcp/config.json (saved by login) or the FRAMEIO_CLIENT_ID env var, so the server needs no extra arguments.

Tools

Hierarchy: account → workspace → project → folder → files. account_id is optional when you have a single account (it's resolved automatically).

74 tools covering essentially the full SDK surface, by area:

Tools are organized into tools_core, tools_assets, tools_review, tools_metadata, tools_search, and tools_admin modules, all registered on one server.

Notes

• Uploads use Frame.io's chunked presigned-URL flow; large videos are split automatically. After upload, Frame.io may still be transcoding — poll get_file_status for processed renditions.
• Downloads default to the original rendition; pass rendition for high_quality, efficient, thumbnail, etc.
• Custom metadata has two layers: account-level field definitions (create_metadata_field, polymorphic — text/number/select/date/rating/etc.) and per-file values (set_file_metadata, bulk across many files). For select/select_multi, the value is a list of the option UUIDs (from list_metadata_fields), not the display names.
• Version stacks group revisions of a clip (v1, v2, …) via create_version_stack from existing file IDs.
• Deletes (delete_file, delete_folder, delete_project, etc.) are permanent.
• list_audit_logs depends on the account plan — Frame.io may return a server error if audit logging isn't enabled for the account.