flora-mcp

Run Flora.ai creative techniques from Claude Code, Claude Desktop, Cursor, or any other Model Context Protocol client.

A local stdio MCP server that wraps Flora's REST API as a small set of MCP tools — list_techniques, get_technique_info, run_technique, download_output, and a couple of helpers. Once installed, you can chat with your favorite LLM client and have it generate studio shots, palettes, mood boards, product animations, and anything else in Flora's catalog.

What this is / what it isn't

It is:

A local MCP server that runs on your machine and exposes Flora's API as MCP tools
A small TypeScript library (flora-mcp/core) that you can import from other Node projects
A reference implementation of the Flora API client for the Anthropic / MCP ecosystem

It isn't:

A web UI for Flora (use app.flora.ai for that)
A hosted service (it runs locally; no auth, no rate limiting)
A way to call Flora from Claude.ai web — Claude.ai only accepts remote MCP connectors over HTTPS, and this is a local stdio server

Prerequisites

Node.js 20+ — node -v should print v20.x or higher
A Flora API key — get one at https://app.flora.ai/projects?openSettings=true&initialTab=apiKeys. Format: ak_... or sk_live_...
An MCP client — Claude Code, Claude Desktop, Cursor, or any other client that speaks the MCP stdio transport

Install

git clone https://github.com/maxberko/flora-mcp.git
cd flora-mcp
npm install
npm run build

npm install runs npm run build automatically via the prepare script, so the dist/ directory is ready immediately.

Configure your API key

The server looks for your key in this order:

Environment variable — FLORA_API_KEY=ak_...
.env file walk-up — starting from the directory where the MCP client launched the server, walk up the filesystem toward /, looking for a .env file containing FLORA_API_KEY=.... First match wins.

Drop a .env somewhere convenient (e.g. your ~/code/.env), or pass the key directly in the MCP client config — both work.

Add to Claude Code (or Claude Desktop)

Add this entry to your claude_desktop_config.json (Claude Desktop) or your Claude Code MCP config:

{
  "mcpServers": {
    "flora": {
      "command": "node",
      "args": ["/absolute/path/to/flora-mcp/dist/src/mcp/server.js"],
      "env": {
        "FLORA_API_KEY": "ak_your_key_here"
      }
    }
  }
}

Or, if you prefer the .env walk-up loader, omit the env block and make sure a .env file lives somewhere above the directory you launch your MCP client from:

{
  "mcpServers": {
    "flora": {
      "command": "node",
      "args": ["/absolute/path/to/flora-mcp/dist/src/mcp/server.js"]
    }
  }
}

Restart your MCP client and you should see six flora tools available.

Example interactions

1. Browse the catalog

"What Flora techniques exist for product photography?"

The client calls list_techniques with category: "Product & E-commerce" and gets back a list of slugs you can use.

2. Check a technique's cost before running it

"How much does palette-pull cost and what does it need?"

The client calls get_technique_info with slug: "palette-pull" (free, no credits charged) and reports back the input schema and runCost.

3. Actually run a technique

"Run studio-shot on this image: https://my-bucket.s3.amazonaws.com/cable.png"

The client calls get_technique_info first to confirm the schema, asks you to confirm the credit cost, then calls run_technique and finally download_output to save the result.

Tool reference

| Tool | When to use | Charges credits? | |---|---|---| | list_techniques | Discover what techniques exist. Optional category filter. | No | | get_technique_info | Look up a technique's input schema and exact runCost. Always call before run_technique. | No | | run_technique | Run a technique with concrete inputs. Polls until done. | Yes | | poll_run | Manually poll a single run, only needed if run_technique timed out. | No | | download_output | Save a Flora output URL to a local file. | No | | get_flora_api_key_status | Check whether a key is configured and where it was loaded from. | No |

How to host input images

Flora's API only accepts HTTPS image/video URLs from a small set of allowed hosts: Flora media, Google Cloud Storage, Amazon S3, ImageKit. Random temporary file hosts (catbox, 0x0.st, imgur) are not accepted and runs that reference them will fail.

For demos and one-off runs, the easiest options are:

Amazon S3 — create a bucket, set object ACL to public-read, paste the https://<bucket>.s3.<region>.amazonaws.com/<key> URL.
Cloudflare R2 — S3-compatible, free tier, public bucket → https://pub-<id>.r2.dev/<key>.
Supabase Storage — create a public bucket, upload your file, copy the public URL.
ImageKit — free tier, drop-in image CDN.

This MCP server intentionally does NOT include a generic upload tool, because the only public hosts that don't require credentials (catbox/0x0) aren't on Flora's allowlist. Pasting a presigned URL from your own bucket is the reliable path.

Troubleshooting

"missing_api_key" / "no key found" The server couldn't find a FLORA_API_KEY in the environment or in any .env file walking up from the MCP client's working directory. Either set the env var directly in your MCP config (env: { "FLORA_API_KEY": "..." }) or drop a .env file somewhere above where you launch your MCP client. Use the get_flora_api_key_status tool to debug.

"input_validation_error" mentioning host Your image URL is on a host Flora doesn't accept. Re-host on S3, R2, Supabase Storage, or ImageKit. See "How to host input images" above.

"insufficient_credits" Top up at https://app.flora.ai.

"timeout" during a run Some techniques (especially video ones) take longer than the default 6-minute polling timeout. Pass a larger timeoutMs in your run_technique call.

Why does run_technique charge credits? Every Flora generation costs credits. Use get_technique_info (free) first to see the exact runCost before confirming. The MCP tool descriptions explicitly tell the LLM client to do this.

Architecture

The repo is split into two layers so the same code can power both the MCP server and any future web app on top of Flora:

src/
├── core/        ← pure TypeScript library: FloraClient, runTechnique,
│                  loadApiKey, listTechniques, downloadOutput, errors, types
└── mcp/         ← thin MCP wrapper: registers each core function as a tool

src/mcp/* may import from src/core/* but never the reverse — no MCP types leak into the core library. External Node consumers can import { FloraClient, runTechnique } from "flora-mcp/core" and skip the MCP layer entirely.

Development

npm install        # installs deps and runs build via the prepare script
npm run dev        # tsc --watch
npm run build      # one-shot build
npm test           # run smoke tests against the built output

To exercise the MCP server interactively without a full client, use the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/src/mcp/server.js

License

MIT — see LICENSE.

MCP Servers