Metadata-Version: 2.4
Name: frameio-mcp
Version: 0.1.0
Summary: Local stdio MCP server over the Frame.io v4 API (Adobe)
Project-URL: Homepage, https://github.com/bowlofarugula/frameio-mcp
Project-URL: Repository, https://github.com/bowlofarugula/frameio-mcp
Project-URL: Issues, https://github.com/bowlofarugula/frameio-mcp/issues
Author-email: bowlofarugula <bowlofarugula@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: adobe,frame.io,frameio,mcp,model-context-protocol,review,video
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: cryptography>=48.0.0
Requires-Dist: fastmcp>=3.4.0
Requires-Dist: frameio>=1.2.1
Requires-Dist: httpx>=0.28.1
Description-Content-Type: text/markdown

# frameio-mcp

A local **stdio MCP server** over the [Frame.io v4 API](https://developer.adobe.com/frameio/),
built with [FastMCP](https://github.com/PrefectHQ/fastmcp) on top of the official
[`frameio`](https://pypi.org/project/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](../../README.md)) 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

```bash
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:

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

## Run the server

```bash
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`):

```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:

| Area | Tools |
|------|-------|
| Identity | `whoami` |
| Accounts / workspaces | `list_accounts`, `list_workspaces`, `show_workspace`, `create_workspace`, `update_workspace`, `delete_workspace` |
| Projects | `list_projects`, `show_project`, `create_project`, `update_project`, `delete_project` |
| Folders | `list_folder`, `list_project_contents`, `show_folder`, `create_folder`, `rename_folder`, `move_folder`, `copy_folder`, `delete_folder` |
| Files | `list_files`, `show_file`, `get_file_status`, `rename_file`, `move_file`, `copy_file`, `delete_file` |
| Transfer | `upload_file`, `remote_upload`, `import_file`, `download_file` |
| Version stacks | `list_version_stacks`, `show_version_stack`, `list_versions`, `create_version_stack`, `move_version_stack`, `copy_version_stack` |
| Comments | `list_comments`, `show_comment`, `create_comment` (timecode/frame), `update_comment` (edit/resolve), `delete_comment`, `add_comment_attachment`, `delete_comment_attachment` |
| Shares | `list_shares`, `show_share`, `create_share`, `update_share`, `delete_share`, `add_share_asset`, `remove_share_asset`, `list_share_reviewers`, `add_share_reviewers`, `remove_share_reviewers` |
| Metadata | `list_metadata_fields`, `create_metadata_field`, `update_metadata_field`, `delete_metadata_field`, `get_file_metadata`, `set_file_metadata` |
| Discovery | `search` (lexical or nlp) |
| Webhooks | `list_webhooks`, `show_webhook`, `create_webhook`, `update_webhook`, `delete_webhook` |
| Permissions | `list_account_users`, `list_workspace_users`, `set_workspace_user_role`, `remove_workspace_user`, `list_project_users`, `set_project_user_role`, `remove_project_user` |
| Audit | `list_audit_logs` |

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.
