midjourney-mcp

FastMCP server for Midjourney image generation via PiAPI, with a daily-USD cost cap, per-call audit log, and SSRF-safe image URL inputs.

Midjourney has no broadly available official API as of May 2026 (Enterprise application-only). This MCP wraps PiAPI's PAYG Midjourney surface — the most stable third-party wrapper at the time of build — behind one consistent tool surface that fits the same audit + safety patterns as the rest of the family (cloudflare-dns-mcp, godaddy-mcp, parse-mcp, etc.).

Why a peer MCP

Other Midjourney MCPs exist (AceDataCloud, z23cc, PiAPI's own TypeScript MCP). This one ships:

1. Daily USD cap. A single env var (MIDJOURNEY_MCP_DAILY_USD_CAP) sets a hard ceiling on per-day image-gen spend. Cost-incurring tools refuse with a stable error_class="rate_cap" once the projected day total exceeds cap.
2. Per-call 4-field audit log (execution_time_ms / io / token_usage / error_class) at ~/.claude/midjourney-mcp/audit.log.jsonl, with actual PiAPI credit consume rolled in on completion.
3. SSRF-safe image URL inputs on describe + blend via mycelium-security sanitize_or_raise + assert_public_ip. Defense in depth — refuses private / link-local / cloud metadata service hosts before forwarding.
4. sanitize_error() strip patterns on every error payload — X-API-Key, Bearer tokens, api_key / secret / password / token patterns get redacted before crossing into model context.
5. admin.env auto-load. Secrets live at ~/.claude/midjourney-mcp/admin.env (chmod 600, gitignored), never inline in .mcp.json.

Install

cd ~/.claude/midjourney-mcp
python3 -m pip install --break-system-packages -r requirements.txt

Then drop the API key into admin.env:

printf 'PIAPI_API_KEY=your-piapi-key-here\n' > ~/.claude/midjourney-mcp/admin.env
chmod 600 ~/.claude/midjourney-mcp/admin.env

Sign up at https://piapi.ai/ if you need a key. PAYG starts at ~$0.01 per imagine task. Host-Your-Account ($8/seat/mo) is also supported — set the daily cap to 0 (MIDJOURNEY_MCP_DAILY_USD_CAP=0) to disable cost tracking in HYA mode.

Register in your project .mcp.json:

{
  "mcpServers": {
    "midjourney": {
      "command": "python3",
      "args": ["/Users/YOU/.claude/midjourney-mcp/server.py"],
      "env": {}
    }
  }
}

Then restart Claude Code.

Tools (11 total)

Read (no cost, no cap)

Tool	What it does
healthcheck	Verify the PiAPI key is set + return today's cap snapshot
account_info	Today's USD cap + per-tool cost estimates + default process_mode
get_task(task_id)	Single poll for task status + output URLs
wait_for_task(task_id, timeout_seconds, poll_interval_seconds)	Block until terminal state
list_recent_tasks(limit)	Scan the local audit log for recent task_ids

Cost-incurring (cap-gated)

Tool	Estimated USD (fast mode)	What it does
imagine(prompt, aspect_ratio, ...)	$0.040	4-up grid from a text prompt
variation(origin_task_id, index, prompt, ...)	$0.040	Regenerate variations off a grid (index 1-4 / high_variation / low_variation)
upscale(origin_task_id, index, ...)	$0.010	Isolate + upscale one grid image (index 1-4 / light / beta / 2x / 4x / subtle / creative)
describe(image_url, ...)	$0.005	4 prompts from an input image (image-to-prompt)
blend(image_urls, dimension, ...)	$0.040	Merge 2-5 images into a new 4-up grid

Lifecycle

Tool	What it does
cancel_task(task_id)	Cancel a non-terminal task

Daily USD cap

Image generation is creative iteration. Draft+confirm on every call breaks the loop. Instead, every cost-incurring tool runs a cap check BEFORE the API call:

projected = spent_today_usd + estimated_call_usd
if projected > MIDJOURNEY_MCP_DAILY_USD_CAP:
    refuse with error_class="rate_cap"

Spent-today tracks the calendar day at a configurable UTC offset (default -5; override via MIDJOURNEY_MCP_TZ_OFFSET_HOURS=-8 for US Pacific Standard, 1 for Central European, etc.). Cap resets at midnight in that offset. Estimates drive the cap (conservative pre-flight); actual PiAPI credit consume is backfilled from meta.usage.consume on task completion and lands in the audit log.

Default cap: $5.00/day. Override via env: MIDJOURNEY_MCP_DAILY_USD_CAP=20.00. Set to 0 to disable (e.g. HYA mode with flat $8/mo billing).

Typical flow

# 1. Submit an imagine
imagine(prompt="a quiet kitchen at dawn, soft window light, film grain --ar 3:2", aspect_ratio="3:2")
# -> {"task_id": "tk_abc...", "status": "pending", ...}

# 2. Wait for it
wait_for_task(task_id="tk_abc...", timeout_seconds=180)
# -> {"status": "completed", "task": {"output": {"image_url": "...", "image_urls": [...]}}}

# 3. Upscale the best one (say grid position 2)
upscale(origin_task_id="tk_abc...", index="2")
# -> {"task_id": "tk_xyz...", ...}
wait_for_task(task_id="tk_xyz...")

# Or vary instead of upscale:
variation(origin_task_id="tk_abc...", index="3", prompt="<same prompt, tweak>")

Audit log

Every tool call writes one JSONL line at ~/.claude/midjourney-mcp/audit.log.jsonl:

{
  "ts": 1737842400,
  "tool": "imagine",
  "execution_time_ms": 1230,
  "io": {"input": {"prompt_chars": 47, "aspect_ratio": "3:2"}, "output": {"task_id": "tk_abc...", "status": "pending"}},
  "token_usage": {},
  "error_class": "none",
  "extra": {"task_id": "tk_abc...", "usd_estimate": 0.04}
}

Search by tool, date, error_class, task_id. Useful for cost attribution + bug triage. Override the path via MIDJOURNEY_MCP_AUDIT_LOG.

Process modes

PiAPI translates process_mode to Midjourney's plan-level modes:

• relax — slowest, cheapest, no GPU minutes consumed on official MJ plans
• fast — default, normal-quality GPU time
• turbo — fastest, premium GPU time, ~2× cost

Override default via env: MIDJOURNEY_MCP_PROCESS_MODE=fast (default). Override per-call via the process_mode argument on any tool.

Aspect ratios

Pass aspect_ratio to imagine / variation. Common values:

• 1:1 (square, default)
• 3:2, 2:3 (classic photo)
• 16:9, 9:16 (cinema / portrait phone)
• 4:3, 3:4 (older monitor / portrait)
• 21:9 (ultra-wide)

PiAPI also accepts Midjourney's --ar W:H flag in the prompt itself; either works, but aspect_ratio is cleaner.

Configuration reference

Env var	Default	Purpose
PIAPI_API_KEY	(required)	PiAPI API key. Auto-loaded from admin.env.
PIAPI_API_BASE	https://api.piapi.ai/api/v1	Override for mocking / testing.
MIDJOURNEY_MCP_DAILY_USD_CAP	5.00	Daily USD spend cap. 0 disables.
MIDJOURNEY_MCP_PROCESS_MODE	fast	Default mode if not specified per-call.
MIDJOURNEY_MCP_AUDIT_LOG	~/.claude/midjourney-mcp/audit.log.jsonl	Audit log path.
MIDJOURNEY_MCP_SPEND_FILE	~/.claude/midjourney-mcp/spend.json	Daily spend tracker path.

Related MCPs

Same author, same install path (~/.claude/<name>-mcp), same safety patterns:

• whatsapp-mcp — WhatsApp Web bridge with draft+confirm sends
• imessage-mcp — iMessage with Whisper voice transcription
• slack-mcp — Multi-workspace Slack with draft+confirm
• substack-mcp — Notes + drafts + post management
• parse-mcp — Multi-backend document parser
• godaddy-mcp — GoDaddy DNS with draft+confirm
• cloudflare-dns-mcp — Cloudflare DNS with draft+confirm
• finance-mcp — Plaid-backed personal finance

License

MIT.

---

Built by Adelaida Diaz-Roa. Full install or team version at diazroa.com.