Fotor Plugin for Agents

Create images and videos with Fotor, directly from your AI agent.

Agents · Features · Codex setup · Claude Code setup · Cursor setup · Pi setup · DeepSeek Harness setup · Documentation

Supported Agents

This snapshot includes Codex and Claude Code and Cursor and Pi and DeepSeek Harness. Installation and live-service acceptance are separate checks; see the verification scope below.

Both release channels connect to Fotor's production service and website. The test channel previews plugin changes; it uses your production account and credits.

Each skill includes its own four runtime reference documents. Platform installation, MCP registration and any external bridge setup remain separate prerequisites.

Features

Available models, parameters, and operations come from the connected Fotor service.

Codex

Installation

Use a Codex version with plugin support and Git access to this public repository. GitHub sign-in is not required to install the public package. If fotor-ai is already registered from another source, follow Switch release channel.

Production release

Install the released plugin from the default main branch. No branch selector is required.

codex plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git
codex plugin add fotor@fotor-ai

Connect

1. Check the installed plugin and enabled state:

   codex plugin list --marketplace fotor-ai --json
   

2. Confirm version 0.5.0, release channel production, and the production MCP endpoint https://mcp.fotor.com/mcp in the installed package. Check any standalone Fotor MCP override before authorization; it must use the same production endpoint.

3. Open a new Codex task and ask:

   Connect to Fotor and introduce its main features.
   

Valid credentials are reused. When authorization is needed, complete Codex's sign-in flow in an external browser, then choose "Signed in and authorized; open Fotor in the in-app browser" in the localized confirmation prompt. You can also choose to keep waiting or cancel. After Codex confirms authorization, the plugin opens the website sign-in link in a visible in-app browser. See the connection workflow for verification and manual fallback.

For a read-only check without opening the website, ask: Check only the Fotor MCP connection.

Updates

Refresh and reinstall from the currently selected channel:

codex plugin marketplace upgrade fotor-ai
codex plugin add fotor@fotor-ai
codex plugin list --marketplace fotor-ai --json

Open a new task and verify the version, enabled state, and endpoint. An update keeps the selected branch; use the next section to change channels.

Codex marketplace migration

Existing fotor-codex installations need this one-time migration; ordinary updates within fotor-ai use the Updates section.

Migration changes the installation identity. Before removing anything, record the old source/ref, scope, version and enabled state, and confirm the destination catalog actually declares fotor-ai. A source still declaring fotor-codex cannot install fotor@fotor-ai. Preserve required plugin data using supported host controls. Never copy tokens or clear credentials to make a migration work.

Outside other catalog-bearing checkouts, remove only the old Fotor installation and its registration:

codex plugin remove fotor@fotor-codex
codex plugin marketplace remove fotor-codex

Removal deletes the old installed cache. Then run the Installation commands above for the verified destination. Check codex plugin list --marketplace fotor-ai --json and the marketplace listing: only one Fotor installation should be enabled, with the intended version, source and production MCP declaration. Open a new task. If migration fails, remove any partial new installation and restore the recorded old source/ref and plugin through native controls. Skip removals already completed; inspect current state before repeating the sequence.

Credential reuse across the identity change requires separate verification; do not promise that a successful installation preserves authorization.

Switch release channel

Use one source for the fotor-ai marketplace. Choose the destination first, then run one of the replacement sequences below. Run source changes outside another checkout containing the same marketplace catalog.

codex plugin marketplace remove fotor-ai
codex plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git
codex plugin add fotor@fotor-ai
codex plugin list --marketplace fotor-ai --json

codex plugin marketplace remove fotor-ai
codex plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git --ref release/test
codex plugin add fotor@fotor-ai
codex plugin list --marketplace fotor-ai --json

After switching, open a new task and verify the destination version and production MCP endpoint. Reuse valid production authorization. If a legacy installation or standalone override uses a different service, stop and update that configuration through the host's controls before connecting; do not migrate its credentials automatically.

Troubleshooting

Claude Code

Claude Code installation

This guide targets Claude Code CLI with plugin support and Git access. The client acceptance baseline is 2.1.296; other CLI versions require their own checks, and Desktop/IDE acceptance remains deferred. Install the whole marketplace package; no interpreter or build step is required.

Production release

Install the released plugin from the default main branch. No branch selector is required.

claude plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git --scope user
claude plugin install fotor@fotor-ai --scope user

Start a new Claude Code session. Check claude plugin list --json for fotor@fotor-ai, version 0.5.0, and its enabled state. Verify the installed .mcp.json uses https://mcp.fotor.com/mcp and resolve conflicting host overrides before connecting.

Claude Code connection

Ask Connect to Fotor and introduce its main features. You can also invoke /fotor:fotor-connect. For a read-only connection check, ask Check only the Fotor MCP connection.

Use /mcp to inspect the plugin's server, normally plugin:fotor:fotor. Reuse valid Claude-managed Fotor credentials. When native status requires login, use its Authenticate action or the supported CLI entry:

claude mcp login plugin:fotor:fotor

Complete OAuth in an external browser, choose Continue in the localized Continue / Wait / Cancel prompt, and wait for the client to confirm success. In Claude Code CLI, open the verified handoff once in an external browser such as Chrome; if the CLI cannot open it, copy the unused link there manually. In Claude Code Desktop, open the handoff once in its built-in browser after external OAuth. If the selected browser control is unavailable, explain the limitation and provide the unused link with instructions for that browser. Manual delivery is not automatic-login verification; Desktop host acceptance remains separate. See Claude authentication and browser guidance.

MCP credentials remain in Claude's supported store. Model questions do not open the website, and connection does not query credits. Check the actual website login state before claiming success.

Claude Code updates

Refresh the selected source, update the package, and start a new session:

claude plugin marketplace update fotor-ai
claude plugin update fotor@fotor-ai
claude plugin list --json

Verify the installed version, source, enabled state, and production MCP endpoint. A local-directory marketplace reads files in place; it does not exercise hosted plugin caching. A cached release needs a version change before an update can be established.

Claude Code marketplace migration

Existing fotor-claude-code installations need a one-time migration to fotor-ai.

Migration changes the installation identity. Before removing anything, record the old source/ref, scope, version and enabled state, and confirm the destination catalog actually declares fotor-ai. A source still declaring fotor-claude-code cannot install fotor@fotor-ai. Preserve required plugin data using supported host controls. Never copy tokens or clear credentials to make a migration work.

The following example is for a user-scoped installation. Use the original scope's controls for project/local installations; managed installations require their administrator. Verify that the native uninstall command supports --keep-data before proceeding. If unavailable, stop to preserve needed data through supported controls first.

claude plugin uninstall fotor@fotor-claude-code --scope user --keep-data
claude plugin marketplace remove fotor-claude-code --scope user

--keep-data retains the old plugin's persistent data; it does not copy that data, saved options or credentials into the new identity. Marketplace removal can remove remaining plugin state, so inspect the selected scope first. Run the Installation commands above for the verified destination. Check the marketplace source and claude plugin list --json for one enabled fotor@fotor-ai with the intended version and production MCP configuration. Start a new session.

If migration fails, remove any partial new installation using the same data-preserving approach and restore the recorded old source/ref, scope and plugin. Inspect current state and skip completed removals when retrying. Authorization reuse is a separate check; do not clear or copy credentials.

Claude Code channel

Both channels use production MCP and credits. A test source pins release/test; the stable source uses main. Ordinary upgrades retain the selected branch.

claude plugin marketplace remove fotor-ai --scope user
claude plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git --scope user
claude plugin install fotor@fotor-ai --scope user
claude plugin list --json

claude plugin marketplace remove fotor-ai --scope user
claude plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins.git#release/test --scope user
claude plugin install fotor@fotor-ai --scope user
claude plugin list --json

Use claude plugin marketplace list --json to verify the source and branch, then start a new session. Keep existing valid production authorization; do not copy tokens from another client or create a duplicate standalone Fotor server to work around plugin loading.

Cursor

Cursor installation

This guide covers Cursor IDE, Cursor CLI, and Grok Bot through the same Cursor package. Use a complete package with .cursor-plugin/plugin.json, mcp.json, skills, references, and assets. No interpreter or build step is required. Cursor Cloud Agent acceptance is separate.

Production release

First confirm main contains the Cursor catalog and plugins/cursor/fotor/ package. Register the selected Git source with the native CLI, then open /plugin (/plugins on clients that show that alias), select fotor-ai and install Fotor. Registration alone does not install the plugin. Both channels use production MCP and accounts.

agent plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins
agent plugin marketplace list --format json
agent

The CLI exposes marketplace management commands; installation happens in its native /plugin interface, not through an agent plugin install shell command. Confirm the selected package is the Cursor package when several platform catalogs coexist. Account-level marketplace registration can be visible outside the current client configuration.

Alternative local loading

For IDE local loading, copy the selected complete package into ~/.cursor/plugins/local/fotor/, reload the window, and inspect Customize. Local imports must be permitted. An installed marketplace plugin of the same name takes precedence; verify the actual source before testing. A symlink to a repository outside the local plugin directory is not a supported installation.

For CLI local loading, start a new native session:

agent --plugin-dir /absolute/path/to/fotor

Verify version 0.5.0, enabled state, discovered skills, and the https://mcp.fotor.com/mcp URL in the installed mcp.json. Resolve conflicting host overrides before connecting. Marketplace installation and local loading are separate routes; do not substitute Codex or Claude commands.

Grok Bot installation and authorization

1. Install Fotor from the fotor-ai marketplace in Cursor using the selected Git source above. A marketplace registration alone does not install the plugin. Use an account-level installation; local IDE folders and CLI --plugin-dir loads do not establish account sharing.
2. Sign in to Grok Bot with that same Cursor account. Open Connect Apps, select the installed/connected list, and find Fotor from fotor-ai. Check version 0.5.0 and source when the host exposes them; account sharing alone does not verify the loaded files.
3. For a connection that needs authorization, choose the native Authorize / Authenticate action and complete login and consent in the external normal browser. Return to Grok Bot; during a chat flow, choose Continue and verify the native connection result. Reuse valid authorization when available.
4. Confirm Connected, inspect available tools, and ask Check only the Fotor MCP connection. A successful read-only call verifies access. This request does not open a website or query balance.

If Fotor is absent, check the account, installation scope and team policy through native controls. Use Grok Bot's own connector controls rather than local CLI authentication or copied tokens. Website requests use its actual visible browser and require signed-in-state evidence; an unavailable browser uses a clearly identified manual link. Use readable attachments or Bot-workspace files for uploads. See the host-specific authentication and browser guide.

After updating the account-installed plugin, recheck it in Grok Bot and use a new conversation. Removing that installation or connection can affect other clients or Bots; preserve valid credentials and inspect the scope first. Website handoff, restart/expiry reuse, and individual media workflows require separate checks; account sharing does not establish all of them.

Cursor connection

Ask Connect to Fotor and introduce its main features. Select the actual connection skill from the native slash menu for an explicit invocation. Ask Check only the Fotor MCP connection to finish without a website link.

Use IDE MCP controls or CLI /mcp to inspect the actual plugin server; Grok Bot uses Connect Apps as described above. When the CLI supports them in the same loading context, agent mcp list, agent mcp list-tools <identifier>, and agent mcp login <identifier> provide native inspection and login. Cursor account login and Fotor MCP OAuth are separate.

Reuse valid Fotor credentials. When authorization is required, complete it in an external browser, choose Continue, and wait for client-confirmed success. Website requests use the IDE's visible built-in browser, the CLI's permitted external-browser opener, or Grok Bot's available visible browser. If unavailable, provide the unused link for the specified browser and await confirmation. Verify the final production website and signed-in state. See Cursor and Grok Bot native guidance.

Cursor updates

For a Git marketplace install, refresh the selected marketplace, then open /plugin and use its update action if available:

agent plugin marketplace update fotor-ai
agent plugin marketplace list --format json
agent

Start a new CLI process and verify the installed version, resolved commit, package files, skills and production endpoint. Registration can store a resolved commit instead of a moving branch; a successful refresh message alone does not prove an upgrade. If the source stays pinned, repeat the selected channel's registration command and check a new process first.

If re-registration is rejected or the old package remains active, record the current source and scope, uninstall only that Fotor installation in /plugin (retain data when offered), run agent plugin marketplace remove fotor-ai for your recorded user-owned marketplace, and repeat the selected channel's registration and native installation steps. Verify the new files in a fresh process. Record this as a marketplace reset and reinstallation, not a successful native refresh. Preserve valid credentials; installation success does not establish authorization continuity. Do not remove a team/global marketplace or use account logout as an upgrade step.

For a local install, obtain the new complete package from the chosen channel, replace only that package, and reload the IDE or start a new CLI session. Local replacement is distinct from Git marketplace refresh and cached upgrades.

Cursor marketplace migration

The catalog identity is fotor-ai; earlier development catalogs used fotor-cursor. Local --plugin-dir or IDE local-folder loads have no marketplace registration to rename. Replace the complete package, keep its directory basename fotor, reload or start a new session, and verify version and source.

For a real old marketplace registration, first verify the destination catalog, record the source and enabled state, and use the owning Cursor installation controls to remove the old Fotor registration and install from the new source. Do not substitute another host's commands. A marketplace rename requires its own migration checks; an installation or update result does not prove migration. Preserve credentials, and restore the recorded old source if the new installation fails.

Cursor channel

Both channels use production MCP and credits. Select one Git marketplace source or one local package, then verify a fresh session uses the intended revision. A channel change is not an MCP environment change.

agent plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins
agent plugin marketplace list --format json
agent

agent plugin marketplace add https://github.com/fotor-ai/fotor-agent-plugins --git-ref release/test
agent plugin marketplace list --format json
agent

Pi

Pi installation

Production release

Install the released plugin from the default main branch. No branch selector is required. First verify that the selected revision contains the Pi package and root Pi manifest. Installation loads skills only; register the Fotor MCP separately.

pi install https://github.com/fotor-ai/fotor-agent-plugins
pi list

Pi installs a Package, not a Marketplace entry. The root manifest selects only the Pi skills. Git installation requires Git and Pi's configured package manager even though Fotor has no dependencies or runtime scripts. A local independent package can instead be installed with pi install /absolute/path/to/fotor; local sources are loaded in place.

Pi MCP registration and connection

Package installation does not register MCP. Inspect /mcp and the effective user/project configuration first; preserve a different existing fotor registration and resolve that choice before adding it. The declarative example describes the production entry:

pi mcp add fotor --url https://mcp.fotor.com/mcp --exposure deferred --description "Connect to Fotor's production MCP service."

Use Pi's native /mcp sign-in or pi mcp login fotor when authorization is required. Complete OAuth in an external ordinary browser, choose Continue / Wait / Cancel conversationally, and verify the native callback before proceeding. Pi's model-provider login is separate. Follow Pi authentication for tool discovery, overrides, and recovery.

Ask "Connect to Fotor and introduce its main features." or invoke /skill:fotor-connect. The website flow opens a fresh validated link in an external ordinary browser when the host can target it; otherwise it supplies a link for immediate manual opening. A native opener's success does not prove website login. An explicit MCP-only request does not create a website link.

Pi updates

Update only the recorded Fotor source, using the same installation scope:

pi update <recorded-source>
pi list

pi update --extensions updates all installed Packages; bare pi update updates Pi itself. Restart Pi and verify the resolved revision, package version, actual skills and production MCP. Git tags and commit selectors remain pinned; check actual installed files after a branch update.

Pi channel

Git Package identity is the repository URL without its ref. Keep one Fotor source per configuration. Record the old source and scope for recovery, remove only that Package, and install the chosen channel; retain MCP registration and authorization. Only use a channel after it contains the Pi package. Append --local to native install/remove commands only when using project scope.

Production release

Install the released plugin from the default main branch. No branch selector is required. First verify that the selected revision contains the Pi package and root Pi manifest. Installation loads skills only; register the Fotor MCP separately. Record the current source and scope, remove that package with pi remove <recorded-source>, then install the selected source in the same scope. Keep MCP configuration and credentials; verify one active Fotor package in a new session.

pi install https://github.com/fotor-ai/fotor-agent-plugins
pi list

Test release

Install the test build from release/test for prerelease validation. First verify that the selected revision contains the Pi package and root Pi manifest. Installation loads skills only; register the Fotor MCP separately. Record the current source and scope, remove that package with pi remove <recorded-source>, then install the selected source in the same scope. Keep MCP configuration and credentials; verify one active Fotor package in a new session.

pi install https://github.com/fotor-ai/fotor-agent-plugins@release/test
pi list

DeepSeek Harness

DeepSeek Harness is abbreviated as dsh in commands and native identifiers.

DeepSeek Harness installation

Production release

First verify that the selected revision contains the DeepSeek Harness Bundle. Install the fixed external bridge separately, then add this package to the chosen profile. Both components stay disabled until local setup.

dsh plugin --profile web add "git+https://github.com/fotor-ai/fotor-agent-plugins.git#main&path:/plugins/dsh/fotor" --ignore-scripts

This is a declarative Bundle for Linux DeepSeek Harness Web 0.2.1-rc.2. It has no runtime module, dependency or lifecycle script. The public source must contain plugins/dsh/fotor before this command applies. Keep the Git subdirectory selector: the repository root is a Pi Package, not the DeepSeek Harness Bundle. Desktop, headless and ACP are outside this baseline.

Installing Fotor does not install mcp-remote. You, or an Agent acting on your installation request, install the pinned bridge outside the Bundle; DeepSeek Harness later starts the configured bridge. Read the complete installation and usage guide before running the install command above:

1. Check the fixed DeepSeek Harness and Node baselines and obtain the complete DeepSeek Harness package.
2. Install the external bridge using the supplied JSON manifest and reviewed lock, with lifecycle scripts disabled.
3. Install Fotor, resolve its actual directory and apply the complete external configuration.
4. Enable skills first; authorize with the standalone bridge client before enabling MCP.
5. Verify actual queries, then use MCP-only or website connection as requested.

The package includes all setup materials. No internal repository document or automatic dependency installer is required. Use one selected source and preserve the external bridge and authorization store on updates.

DeepSeek Harness configuration and connection

Installation adds two disabled components. Follow the guide's native root and dependency queries to resolve the installed path and source; why fotor alone proves neither. Copy the full native configuration example outside that directory. Fill all absolute paths and select a free callback port. Add both complete override rows to the chosen profile's native patch, or use its native --patch launch option. Overrides replace whole config objects; they do not deep-merge fields.

The skill provider scans only the installed Fotor skill directory, with default roots disabled. Enable skills first; leave the MCP row disabled. The MCP client directly invokes the separately installed bridge using structured command, args, env and cwd. Keep MCP_REMOTE_CONFIG_DIR dedicated to Fotor, outside package updates, and keep native automatic reconnect disabled. Resolve any existing fotor registration before enabling another.

Follow DeepSeek Harness authentication for standalone bridge authorization, native status verification and controlled recovery. OAuth is bridge-managed. Authorize with the fixed bridge client first, then enable the proxy using exactly the same store and connection arguments. User login, consent and Continue / Wait / Cancel remain explicit. Use the confirmed daily ordinary browser for authorization and website access; preserve its login state and data.

Invoke /fotor-connect through the actual skill menu or ask "Connect to Fotor and introduce its main features." Verify the loaded skill's source and perform a real model query. For MCP-only checks, do not request a website link. Website handoff opens the original production link once, using native single-command approval when necessary; user confirmation establishes the final login state. Manual opening is a separate fallback, and an already signed-in browser does not establish first-time website login.

DeepSeek Harness updates

dsh plugin --profile web update fotor --ignore-scripts
dsh plugin --profile web why fotor

Inspect the resolved Git commit, version and files, update the absolute skill directory if its location changed, and restart into a new session. Retain the original pnpm store; see the guide when a dedicated --store-dir was selected. Verify only one Fotor skill source. Keep the bridge version, credential directory and security arguments unchanged. If native update remains on the old commit, retain that failure and use native removal/addition of the recorded source only as a separately reported reinstall path; do not modify caches.

DeepSeek Harness source selection and removal

Production release

First verify that the selected revision contains the DeepSeek Harness Bundle. Install the fixed external bridge separately, then add this package to the chosen profile. Both components stay disabled until local setup. Record the old source and scope, remove only this Fotor Bundle through native controls, then add the selected source. Preserve the external bridge and its credential directory; check the installed skill path before enabling the new package.

dsh plugin --profile web add "git+https://github.com/fotor-ai/fotor-agent-plugins.git#main&path:/plugins/dsh/fotor" --ignore-scripts

Test release

First verify that the selected revision contains the DeepSeek Harness Bundle. Install the fixed external bridge separately, then add this package to the chosen profile. Both components stay disabled until local setup. Record the old source and scope, remove only this Fotor Bundle through native controls, then add the selected source. Preserve the external bridge and its credential directory; check the installed skill path before enabling the new package.

dsh plugin --profile web add "git+https://github.com/fotor-ai/fotor-agent-plugins.git#release/test&path:/plugins/dsh/fotor" --ignore-scripts

Before removal, disable the two Fotor components and remove only their external override rows. Run dsh plugin --profile web remove fotor --config.ignore-scripts=true in the original profile and store. This baseline does not accept --ignore-scripts for removal. Preserve the external Fotor credential store and browser state for a later reinstall; local store deletion is not server-side revocation. Configuration, installation, OAuth, tool execution, restart reuse and controlled reauthorization recovery require separate evidence.

Documentation

• Codex plugin guide
• Claude Code plugin guide
• Cursor plugin guide
• Pi plugin guide
• DeepSeek Harness plugin guide

Verification scope

Package checks cover files, references, and configuration. Verify installation, MCP authorization and calls, website login, credit links, uploads, and media execution separately in the selected host and environment. A release or model query does not establish successful website login or completed media results.

License

Apache-2.0