@tenpo/image-mcp

Portable image-prompt + image-generation MCP. Faithful to the gpt-image-2 structuring skill (object / scene / vibe / photo-quality / aspect / avoid fields). Multi-backend: OpenAI, Replicate, fal.ai — auto-selected by whichever API key you provide.

Works in: Claude Code · Cursor · Cline · Claude Desktop · Windsurf · any MCP host.

Install

Add this to your MCP host config (Claude Code = ~/.mcp.json, Cursor = ~/.cursor/mcp.json, etc.):

{
  "mcpServers": {
    "image": {
      "command": "npx",
      "args": ["-y", "@tenpo/image-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Or use REPLICATE_API_TOKEN (Flux 1.1 Pro, ~$0.04/image), or FAL_KEY (fal.ai Flux Pro, fastest at ~2-3s, ~$0.04/image). Backend is auto-selected from whichever key is set.

Tools

| Tool | What it does | |---|---| | image_generate({idea, style?, aspect_ratio?, backend?}) | Structures the prompt + generates the image in one call. Returns image URL + the prompt used. | | image_structure_prompt({idea, style?, aspect_ratio?}) | Structures the prompt only (no generation). For review or for piping to non-MCP tools. | | image_list_backends() | Diagnostic — shows which API keys are configured and which backend would be picked by default. |

Categories (auto-detected from keywords)

• ugc — phone-recorded, raw, imperfect, mid-action. Best for ads/unboxing/reactions.
• realistic — non-studio, iPhone vibe. Default.
• cinematic — movie-still, warm rim light, film grain, vignette.
• infographic — technical flow diagrams.
• ad — clean composition, no text/watermarks, branded but natural.

Aspect ratios (auto-detected, override with aspect_ratio)

• 9:16 — TikTok / Reels / Stories / phone-vertical
• 16:9 — banners / heros / cinematic
• 1:1 — Instagram feed
• 4:5 — magazine / poster
• 4:3 — default

Backend costs

| Backend | Model | Approx cost/image | Latency | |---|---|---|---| | OpenAI | gpt-image-1 or dall-e-3 | $0.04 – $0.19 | 5-15s | | Replicate | Flux 1.1 Pro | $0.04 | 8-20s | | fal.ai | Flux Pro 1.1 | $0.04 | 2-3s (fastest) |

Example

image_generate({
  idea: "Indian woman in her late 20s unboxing a Claw Store snowboard in her apartment, surprised reaction, vertical phone video frame",
})

// Returns:
// {
//   image_url: "https://...",
//   backend: "openai",
//   model: "gpt-image-1",
//   generation_ms: 8420,
//   category: "ugc",
//   aspect_ratio: "9:16",
//   prompt: "...the full structured prompt..."
// }

License

MIT