Gemini CLI · ~/.gemini/settings.json · httpUrl

Image generation in Gemini CLI: MCP server setup

Add an mcpServers entry to ~/.gemini/settings.json using httpUrl — not url — and eleven image tools appear in the next Gemini CLI session. Gemini CLI already reads and writes the files in your project. What it cannot do out of the box is produce the images those files reference, so a build ends with real markup pointing at placeholder art.

By the imagemcpserver.com teamPublished 9 September 2026Gemini CLI docs checked September 2026

Get a free API key Generic MCP docs

Add the server

Where the config lives: ~/.gemini/settings.json (user) · .gemini/settings.json (project)
The key it nests under: mcpServers

1
Create an API key. Create a key in the imagemcpserver dashboard.
2
Open settings.json. Edit ~/.gemini/settings.json, or .gemini/settings.json inside the project.
3
Add the entry under httpUrl. Use httpUrl for this streamable HTTP endpoint and pass the key as an x-api-key header.
4
Restart and check. Start a new session and run /mcp to see the server and its tools listed.

gemini cli · recommendeduse this

{
  "mcpServers": {
    "imagemcp": {
      "httpUrl": "https://mcp.imagemcpserver.com/mcp",
      "headers": { "x-api-key": "sk-img-gen-…" },
      "timeout": 30000
    }
  }
}

Project-scoped instead of global

# .gemini/settings.json, committed with the repo.
# Read the key from the environment so the file is safe to commit.
{
  "mcpServers": {
    "imagemcp": {
      "httpUrl": "https://mcp.imagemcpserver.com/mcp",
      "headers": { "x-api-key": "$IMAGEMCP_API_KEY" }
    }
  }
}

httpUrl, not url

Gemini CLI treats url and httpUrl as two different transports: url is an SSE endpoint, httpUrl is streamable HTTP. Putting a streamable HTTP endpoint in url is the single most common reason a Gemini CLI config connects to nothing. This server is streamable HTTP, so it goes in httpUrl.

The endpoint and the key are identical in every client. The wrapper around them is not, and that wrapper is where almost every “correct” config that does nothing goes wrong. Checked September 2026 against Gemini CLI’s own documentation — see the sources below.

Three ways to send the key

The server resolves your API key from any of these, checked in this order. That matters when a client only gives you a URL field and no way to set a header — you are not stuck, and you do not need a bridge process.

Query parameter

?apikey=sk-img-gen-…

Checked first. The fallback for a client whose config is a bare URL field.

x-api-key header

x-api-key: sk-img-gen-…

The documented default, and what every client below uses unless noted.

Authorization header

Authorization: Bearer sk-img-gen-…

Accepted as a bearer token, which is what a client with only a token field will send.

A key in a query string ends up in shell history, process listings and any log the client keeps, so prefer a header where the client allows one. Where it does not, treat the whole URL as the secret and rotate it as freely as you would a password.

What each tool costs

Wherever Gemini CLI lets you approve tools individually, the useful line to draw is not between image tools and other tools — it is between calls with a fixed price and calls that route to a model.

get_user_infolist_models

free

Safe to auto-approve wherever the client supports it. These are how the agent finds out what it can afford before it spends anything.

compress_imageconvert_format

1 credit

Deterministic and cheap. Auto-approving these makes an optimisation pass over a whole folder painless.

remove_backgroundtext_to_svgupscale_image

5–15 credits

Fixed prices, no model routing. Auto-approve once you trust the workflow.

generate_imageedit_imagegenerate_transparent_imagemulticall

model-priced

These route to an image model and are the ones that can run up a bill in a loop. Keep approval on.

Gemini CLI questions

How do I add an MCP server to Gemini CLI?

Add an entry to the mcpServers object in ~/.gemini/settings.json for every project, or .gemini/settings.json inside one project. There is no separate install step — the CLI reads the file at startup and connects to whatever it finds there.

Why does my Gemini CLI MCP server never connect?

Almost always the transport field. url means SSE to Gemini CLI, and httpUrl means streamable HTTP. A streamable HTTP endpoint placed in url will not work, and the failure is quiet rather than loud. Checked September 2026.

Can I keep the API key out of settings.json?

Yes. Gemini CLI expands environment variables in the config, so "$IMAGEMCP_API_KEY" inside the headers object resolves at startup. That makes a project-scoped .gemini/settings.json safe to commit.

Does the free Gemini CLI tier work with this?

Yes. The MCP connection is between the CLI and this server; whatever model tier you use for the conversation is unrelated. Image credits are billed by this server, not by Google.

How do I confirm the tools loaded?

Run /mcp inside the session. It lists each connected server with its tool names, which is faster than guessing from a failed prompt.

Sources & references

Codex →Zed →All clients