Flo Plugin for Claude

The official Flomenco plugin for Claude. Brings Flo's AI-powered media automation into Claude Code via slash commands, and connects Claude Desktop to the Flo platform via MCP.

Do not use npx @flomenco/claude-plugin-mcp in Claude Code — npm is stuck at 0.2.2 without AgentCore SSE parsing, so flo_happy_path_run fails while individual tools appear to work. Use marketplace install (or node scripts/run-mcp.js from this repo).

Quick start (Claude Code)

1. Install the plugin

In Claude Code:

/plugin marketplace add Flomenco-Inc/flo-plugin
/plugin install flo-plugin@flo-plugins
/reload-plugins

2. Authenticate

Ask Claude to run flo_auth_login — it opens a browser window, completes the OAuth flow, and caches your token locally. You only need to do this once (or when your token expires).

Production: the plugin ships prod defaults in .mcp.json. Copy your OAuth client ID from floapp.co/settings/api (Claude Plugin tab) into the plugin MCP env only if flo_auth_login reports a missing client ID.

Dev / staging: marketplace .mcp.json ships prod defaults. Override using any of:

1. ~/.flo/claude-plugin-mcp.env — copy the env block from Settings → API → Claude Plugin (recommended).

2. Legacy ~/.claude.json — if you already have mcpServers.flo-plugin.env for a manual MCP server, the plugin MCP merges those vars automatically.

3. Claude Code plugin MCP env UI for plugin:flo-plugin:flo-plugin.

Run npm run sync-versions before release so marketplace.json matches package.json (required for /plugin marketplace update to pull new builds).

3. Validate

flo_plugin_healthcheck
flo_happy_path_run

Windows, macOS, and Linux

The MCP server starts via node scripts/run-mcp.js (see .mcp.json). You need Node.js ≥ 22.13 and npm on your PATH. No Bash or WSL required.

• Config and tokens live under %USERPROFILE%\.flo\ on Windows and ~/.flo/ on Unix.

• OAuth login opens your default browser (cmd /c start on Windows).

• Optional env overrides: %USERPROFILE%\.flo\claude-plugin-mcp.env (Windows) or ~/.flo/claude-plugin-mcp.env (macOS/Linux).

Related MCP server: facets-control-plane-mcp-server

Commands

MCP tools

Claude Desktop installation

Run the install script (requires AWS credentials with Cognito read access):

npx @flomenco/claude-plugin-mcp install:claude-desktop

Or clone the repo and run:

node tools/install-claude-desktop.js

Then fully quit and relaunch Claude Desktop.

Troubleshooting

flo_auth_login fails with "Invalid URL" or missing client ID Open floapp.co/settings/api, copy the OAuth client ID from the Claude Plugin tab, and set FLO_OAUTH_CLIENT_ID in your MCP env block. For dev, copy the full env block from that page.

flo_plugin_healthcheck returns unreachable Check that you have network access to plugin.floapp.co. If you're on a VPN, try disconnecting.

Commands not appearing after install Restart Claude Code, or run /reload-plugins.

Token expired Ask Claude to run flo_auth_logout followed by flo_auth_login.

Contributing

See CONTRIBUTING.md for how to add new tools or commands.

License

MIT — see LICENSE.