Midjourney MCP Server & CLI README

Midjourney MCP + CLI

Midjourney MCP server and CLI for Claude Code, Codex and AI agents. 32 tools for generating images, following jobs to completion, downloading the real files, and building moodboards that make a style reusable.

Midjourney publishes no API, so this drives a real Chrome that is signed in as you.

There is no key to paste and no cookie to export. You sign in once, in a window, and the session lives in a browser profile rather than in a config file.

32 tools, on both surfaces. It waits for jobs to finish and hands back the actual files, not a screenshot of them.

Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI.

Two ways to use it

Command line

midjourney-cli in your terminal, for scripting, cron, pipes, or a quick question without opening anything:

midjourney-cli                                        # every command, one line each
midjourney-cli login                                  # sign in once, in a window
midjourney-cli imagine "a red fox in snow" --ar 16:9 --confirm
midjourney-cli list-jobs --limit 5 --select id,prompt --json
midjourney-cli download-job <job-id> --out-dir ./renders
midjourney-cli list-moodboards --json | jq -r '.moodboards[].title'
midjourney-cli which "save my pictures to disk"       # find the right command
midjourney-cli <command> --help                       # what any command takes

--confirm is the shell spelling of the confirmation that generating requires. --json gives JSON, --compact puts it on one line, --select id,status keeps only the fields you name, and errors are JSON on stderr whichever you pick.

Handlers return data rather than pre-rendered text, so --json gives real fields on every command and jq works the same way everywhere.

MCP server, for your AI app

midjourney-mcp is what Claude Code, Claude Desktop, Cursor and the rest launch. You never run it by hand:

claude mcp add midjourney -- npx -y @thenavidm/midjourney-mcp-cli@latest

There is nothing to put in -e. Run midjourney-cli login first.

Then just ask: "shoot that campaign in the style of my High Fashion moodboard".

Every other client is in section 3. Each generation waits for your approval in the client, as section 7 explains.

Which one

They are the same program reading the same tool definitions, so anything one can do, the other can.

Features

Every tool is both a command and an MCP tool, with the same name. The command is the tool name with dashes.

All 27 with their arguments are in section 6.

Contents

1. What you can ask it

• Make me a 16:9 hero image of a red fox asleep in snow, muted palette
• Shoot that campaign in the style of my High Fashion moodboard
• Make a moodboard for cold Nordic product shots, fill it, then shoot a jar of face cream in that style
• Generate four logo concepts at low stylize so they stay literal, and save them
• Vary the second one, strong, and save the results
• Upscale that one and turn it into a video
• Take that last image's seed and try it again with chaos 40
• What is in my Midjourney queue right now?
• Download everything I generated today into ./renders
• Show me my last ten jobs with just the prompt and the image URLs
• Re-run job 3f9c1a2b with the prompt changed to say "at dusk"

The thing you cannot do without this: hand an agent a brief and get finished image files back. Every other route stops at a job id, or at a screenshot of the image rather than the image. This waits for the render and writes the real bytes to disk, so the next step in a pipeline has something to open.

2. Sign in once

There is no API key. Midjourney does not issue one, and this server never handles a credential of any kind.

Instead it runs Chrome against a profile of its own, at ~/.midjourney-mcp/chrome-profile. You sign in there once and the session persists, exactly as it would in a browser you use by hand.

npx -y @thenavidm/midjourney-mcp-cli@latest login

A Chrome window opens on midjourney.com. Sign in. The command waits, notices, and exits.

The profile is separate from your everyday Chrome on purpose. Nothing here can see your normal browsing, your other logins, or your history, and your normal browser does not need to be running.

To revoke it, sign out in that window, or delete the profile:

rm -rf ~/.midjourney-mcp/chrome-profile

3. Install

The long version, every step with what to do when one fails, is in INSTALL.md.

Node 22 or newer, and Google Chrome. Nothing else.

npx -y @thenavidm/midjourney-mcp-cli --version

Node 22 is the floor because the browser connection uses the global WebSocket that landed in that release. That is also why it has no dependency doing it.

Claude Code

claude mcp add midjourney -- npx -y @thenavidm/midjourney-mcp-cli@latest

--scope user makes it available in every project rather than the current one.

Claude Desktop

{
  "mcpServers": {
    "midjourney": {
      "command": "npx",
      "args": ["-y", "@thenavidm/midjourney-mcp-cli@latest"]
    }
  }
}

There is also a one-click .mcpb bundle on the release page, installed through Settings, Extensions, Install Extension.

[!TIP] Claude Desktop does not inherit your shell PATH, so a bare npx can fail silently. Use the absolute path from which npx, and fully quit the app rather than closing the window.

Cursor

.cursor/mcp.json, the same JSON shape as Claude Desktop, key mcpServers.

VS Code

.vscode/mcp.json. The key is servers, not mcpServers, and the entry takes "type": "stdio".

{
  "servers": {
    "midjourney": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/midjourney-mcp-cli@latest"]
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.midjourney]
command = "npx"
args = ["-y", "@thenavidm/midjourney-mcp-cli@latest"]

The shell

Both binaries come from the same install. midjourney-cli with no arguments lists every command.

midjourney-cli install claude-code (or codex, claude-desktop, cursor, vscode, gemini) adds the server to a client in its own format; add --dry-run to see the change first.

Check it worked

npx -y @thenavidm/midjourney-mcp-cli@latest doctor

It checks in dependency order and stops at the first real problem, because these failures all produce the same symptom from a tool call and need completely different fixes.

The two that actually happen:

Browser running fails. Chrome is not up on the DevTools port. It starts on demand on the first tool call, so this is only a problem if you have set MIDJOURNEY_CHROME_LAUNCH=0. Run login to start it by hand.

Signed in fails. The window is open but the profile is signed out. Run login again.

4. Output and exit codes

Results on stdout, errors on stderr as JSON, so one parse handles both.

--select matters more here than it looks. One explore page is tens of kilobytes, most of it layout metadata, and an agent piping that into its context pays for every byte.

--agent deliberately does not imply confirmation, unlike the equivalent in some other CLIs. A flag an agent passes by habit must never be the thing that authorises a charge.

5. Which surface, and what each costs

Both surfaces are the same program with the same 32 tools. The difference is when the model pays for them. Measured in Claude Code:

Claude Code's tool search is on by default: it sends only the tool names and the server instructions, and loads a tool's full definition when the model reaches for it. An app that loads every tool up front pays the first line on every message, whether Midjourney comes up or not. With the skill added, Claude Code also lists its one-line description, about 90 tokens.

To spend less, turn the server off when you are not using it, which in Claude Code is the /mcp panel. MIDJOURNEY_READ_ONLY=1 takes the 15 write tools off the list, leaving 17. Or install the CLI and add the server on the days it earns its place.

Measured on 2026-10-05 with Claude Code 2.1.286 on Claude Opus 5.5: one short prompt with and without the server connected, once with ENABLE_TOOL_SEARCH=false and once with the default, the difference read from the API's own usage figures. SKILL.md was measured the same way. Other apps and models count tokens a little differently.

Against 1.3.1, measured the same day: every tool loaded costs 13,904 tokens instead of 15,243, tool search the same, and SKILL.md 140 more, because it now names all ten tools that spend where 1.3.1 named four, with the approval rule and the full exit codes. In Codex 0.159.3 on gpt-6.1-sol, the same task, "find the command that makes variations of one image from a finished job and the flags it requires", read a median of 84,264 input tokens on 2.0.0 against 85,194 on 1.3.1 over the CLI, and 48,950 against 48,936 over MCP, five runs each. Codex reads MCP tools by printing them from a script and cuts that printout to the same length on both sides, so the 14 extra tokens are a different slice of the same list. By Codex's own count the full list is 701 tokens longer on 2.0.0, for one reason: the shorter approval note brings imagine under the size where Codex leaves out argument descriptions, so imagine now reaches Codex with all 31 arguments explained, where 1.3.1 sent it with none.

6. Tools

Making images

Following work

Getting the files

Moodboards and style

Your account

Explore, and the escape hatch

midjourney-cli which "<what you want>" resolves a capability described in words to the command that does it, so you do not have to read this table.

7. Spending safely

Reads work freely. What is guarded is spending.

Every generation burns GPU time from a paid plan and there are no refunds, so the 10 tools that spend it wait for your approval: imagine, submit_imagine, rerun_job, vary_image, upscale_image, animate_image, pan_image, zoom_out, remix_image and submit_raw_job. remove_from_moodboard asks too.

In a terminal that is --confirm, which --agent never adds. Over MCP a person approves each call where the client can ask: Claude Code (2.1.246 and later) shows its own prompt, and a client that can show forms asks with an approval form whose one box starts unticked. Each approval is signed, bound to that exact call and works once. Where a client can do neither, the model's confirm: true counts, and it should pass it only when you asked for that image. MIDJOURNEY_CONFIRM=model makes confirm: true enough everywhere, for an agent with no person to ask.

Adding to a moodboard does not ask, and neither do downloads. Approving harmless things is how people learn to click yes by reflex, which defeats the gate on spending.

A generation is not annotated destructive, because it destroys nothing. It is a write that spends: it needs approval and MIDJOURNEY_ALLOW_DESTRUCTIVE=0 refuses it, so a client deciding what to auto-approve is told the truth about what it is approving.

MIDJOURNEY_READ_ONLY=1          removes every tool that is not a read, 17 remain
MIDJOURNEY_ALLOW_DESTRUCTIVE=0  keeps reads and downloads, blocks anything that spends
MIDJOURNEY_AUDIT_LOG=<path>     one JSON line per attempted change, allowed and blocked, and who approved it

8. Prompts and parameters

Write the subject in prompt and everything else as named arguments. Do not put --ar inside the prompt string.

The arguments are validated before anything is spent. Midjourney is not: it silently ignores or clamps most malformed parameters rather than reporting them, so a typo costs a generation and comes back looking like a bad result rather than a mistake.

At the terminal, Midjourney's own spellings work as aliases: --ar, --sref, --oref, --iw, --sw, --ow, --q, --no, --v.

9. Moodboards

A moodboard is a set of images the account has curated. Applying one is the same mechanism the web app's Personalize panel uses: the board becomes a personalization code on the prompt, resolved for you from its name.

midjourney-cli imagine "a ceramic jar of face cream" --moodboard "Nordic Skincare" --confirm

That is worth stating because there is a plausible wrong way to do the same thing: sampling the board's images into --sref URLs. It only registers at a high --sw, and that weight is what makes output look over-processed. The personalization code needs no weight and does not compete with your wording.

The loop:

midjourney-cli create-moodboard "Nordic Skincare"
midjourney-cli imagine "<a long, specific style description>" --confirm
midjourney-cli add-to-moodboard "Nordic Skincare" --job-id <job>
midjourney-cli imagine "a ceramic jar of face cream" --moodboard "Nordic Skincare" --confirm

Partial names work: "High Fashion" finds "High Fashion | Woman". An ambiguous name errors with the candidates rather than guessing, because picking the wrong board costs a generation to discover.

--p accepts several codes, so a moodboard and a personalization profile apply together. profile is the other kind of personalization: it biases toward images the account has rated, rather than toward a set of pictures.

Leave the sliders alone

Midjourney's own defaults for stylize, weirdness and variety sit near the minimum. Raising stylize trades fidelity for a prettier, more generic image. Set them when you want that; otherwise a strong result comes from the prompt and the reference.

10. How it works

Midjourney publishes no API. The endpoints under /api/ are the ones its own web app calls, and they sit behind a Cloudflare interstitial that answers a plain client with a 403 challenge page rather than JSON.

That challenge is not defeated by a header. The cf_clearance cookie is bound to the IP, the User-Agent and the TLS fingerprint together, so a cookie lifted out of a browser and replayed from Node is a different client and gets stopped.

So rather than impersonate a browser, this drives one. Requests are issued by fetch() running inside a real midjourney.com page, in a real Chrome that is really signed in. Same origin, same cookies, same fingerprint, same IP, credentials attached by the browser itself. There is nothing to spoof because nothing is being faked.

Chrome 136 stopped honouring --remote-debugging-port on the default profile, so this owns a profile instead: a dedicated user-data-dir you sign into once.

Both surfaces come from one ALL_TOOLS array through Slipway, which serves each tool as an MCP tool and as a shell command through the same handler and the same write guard, so a tool added tomorrow is a command tomorrow and the two cannot drift. A test asserts that.

Downloads are read with an in-page fetch, which needs no new tab and no visible activity. The CDN sends access-control-allow-origin: *, so the bytes come back exactly as served.

11. Your data

Nothing leaves your machine except the requests to Midjourney that you asked for. There is no telemetry, no analytics and no backend.

The session lives in a Chrome profile on your own disk. This process never reads a cookie, stores a token, or sees a password.

Downloads go where you point them, ~/Downloads/midjourney by default. The audit log, when enabled, is a local file.

12. Risks

This is unofficial, and Midjourney's terms do not permit automated access. Every unofficial client carries a risk to the account, this one included. It moves at human pace and acts through a real browser session rather than imitating one, which is the honest limit of what any tool here can do about that.

It spends money. A loop over twenty prompt ideas is twenty charges. Use MIDJOURNEY_READ_ONLY=1 when pointing an unattended agent at the account, and MIDJOURNEY_AUDIT_LOG when you want a record.

The endpoints are undocumented and can change without notice. Job records are parsed defensively and partial answers are preferred to failures, but a large enough upstream change will still break something.

13. Troubleshooting

Start with doctor. It orders the checks so the first failure is the one to fix.

14. Environment variables

Every one of these is optional. The defaults are what you want unless you are doing something unusual.

15. FAQ

Questions

Run into a problem or have a question? Open an issue and I will help.

About the author

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.

Links

• Personal website: navid.me
• Link in bio: navid.bio
• Navid Media: navid.media
• YouTube: @thenavidm and @thenavidai
• X: @thenavidm
• Instagram: @thenavidm
• LinkedIn: thenavidm

Dependencies

The browser connection uses Node's built-in WebSocket and needs nothing else.

License

MIT. Free to use, modify, and share.

Not affiliated with, endorsed by, or sponsored by Midjourney, Inc. Midjourney is a trademark of Midjourney, Inc.

© 2026 Navid Media. Made with ❤️ by Navid Moazzez.