Generates and edits images by driving the OpenAI Codex CLI through your existing ChatGPT subscription.
Also known as glassd/Pixmith
- Stars
- 5
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 6, 2026
- License
- MIT
What is Pixmith MCP?
Pixmith generates and edits images by driving the OpenAI Codex CLI through your existing ChatGPT subscription. It exposes 6 tools, such as generate_image, edit_image, get_image_result.
Summary generated from the project's README
About Pixmith MCP server
Generating and editing images directly from an MCP client like Claude Desktop is what Pixmith enables. By driving the OpenAI Codex CLI, this local server allows you to create visual content using your existing ChatGPT subscription. This means you can generate high-quality images without needing a separate, metered image API key, as the process runs against your current ChatGPT plan limits.
Users can utilize the generate_image tool to create new visuals from text prompts or use edit_image to modify existing files or previous results. The server provides live progress updates and tracks your remaining Codex usage to ensure you stay within your plan limits. It works on macOS, Windows, and Linux, supporting both ChatGPT account authentication and OpenAI API key configurations through the Codex CLI.
What you can do with it
- 1Create new images from textAsk your AI client to generate a specific scene like a watercolor fox at a certain resolution.
- 2Modify existing visual assetsInstruct the AI to change specific details of an image you have already generated or a local file.
- 3Monitor subscription usageKeep track of how much of your ChatGPT plan's image generation capacity remains.
- 4Stop active generation jobsImmediately terminate a running image generation session if it is no longer needed.
Written from the project's README. Every use case is checked against a quote from it.
How to install Pixmith MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Pixmith MCP in Claude Code
$ claude mcp add pixmith -- npx -y pixmithInstall Pixmith MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"pixmith": {
"command": "npx",
"args": [
"-y",
"pixmith"
]
}
}
}Install Pixmith MCP in VS Code
.vscode/mcp.json
{
"servers": {
"pixmith": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"pixmith"
]
}
}
}Install Pixmith MCP in VS Code CLI
$ code --add-mcp '{"name":"pixmith","type":"stdio","command":"npx","args":["-y","pixmith"]}'Install Pixmith MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"pixmith": {
"command": "npx",
"args": [
"-y",
"pixmith"
]
}
}
}Install Pixmith MCP in Codex
$ codex mcp add pixmith -- npx -y pixmithInstall Pixmith MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.pixmith] command = "npx" args = ["-y", "pixmith"]
Install Pixmith MCP in Gemini CLI
$ gemini mcp add -s user pixmith npx -- -y pixmithInstall Pixmith MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"pixmith": {
"command": "npx",
"args": [
"-y",
"pixmith"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for pixmith 0.6.1 in an isolated container with no network and no keys. It answered and listed 6 tools.
Pixmith MCP tools 6
Read from the server with tools/listgenerate_imageGenerate an image from a text prompt using the OpenAI Codex CLI (gpt-image-2 via the $imagegen skill). Runs on the user's signed-in ChatGPT subscription — no API key — and counts toward the ChatGPT plan's usage limits. A generation typically takes ~40s. This call waits up to ~45s: if the image is ready in time it is returned directly (status "done", saved path plus the image inline). Otherwise it returns status "running" or "queued" with a job_id — then call `get_image_result` until it is done. To change a finished image, call `edit_image` with its path. To stop a job, call `cancel_image`.
edit_imageEdit an existing image with a text instruction (gpt-image-2 via the Codex CLI, on the user's ChatGPT subscription). Use it to refine a previous Pixmith result or to change any local image: replace a background, add or remove an object, change lighting or style, fix text. The source file is never modified — the edit is saved as a new PNG. Behaves like generate_image: waits up to ~45s and returns the image directly when ready, otherwise a job_id for `get_image_result`.
get_image_resultFetch the result of a generate_image / edit_image job. Waits up to ~45s for it to finish. If the returned status is "queued" or "running", call this again — repeat until status is "done". On success it returns the saved absolute PNG path and, when small enough, the image inline. Always pass the job_id you were given: this server may be shared with other conversations. Without one, the call picks the only job whose result has not been collected yet (so a result can still be recovered if an earlier call timed out), else the only job that finished in the last 10 minutes; when several could be meant it fails with [ambiguous_job] and lists their job_ids. A finished image's job_id keeps working later, even after a restart.
cancel_imageCancel a queued or running image job. A running job's Codex session is stopped immediately, so it stops consuming the ChatGPT plan's quota. Always pass the job_id: this server may be shared with other conversations. Without one, the call cancels the only queued or running job; when there are several it cancels nothing, fails with [ambiguous_job] and lists their job_ids.
list_imagesList images Pixmith made earlier, newest first, with each one's path, prompt, size and job_id — to find an earlier image again, e.g. to show it or to edit it with edit_image. Covers every output folder. Images deleted since are left out.
pixmith_statusCheck whether Pixmith can make images, without making one (uses no plan quota): whether Codex is installed and its version, whether it is signed in with the ChatGPT account, how much of the plan's usage is left, whether the output folder is writable, and jobs in progress. Use it when the user asks about setup or usage, or after a binary_missing or not_signed_in error. Each problem found comes with what to do about it.
Configuration
CODEX_BIN
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubPixmith
Generate images from your MCP client (e.g. Claude) using the OpenAI Codex CLI — on your ChatGPT subscription, no image API key required.
Pixmith is a small local MCP server that lets any MCP
client (such as Claude Desktop or Claude Code) generate and edit images. Under the
hood it drives the OpenAI Codex CLI and its built-in $imagegen skill
(gpt-image-2), then hands the finished PNG back to your client — both as a file path
and inline. Ask Claude for "a watercolour fox at dawn, 1536×1024" and a real image
lands on disk about half a minute later; then say "make it snowing" and Pixmith edits
that same image.
- One call in the common case.
generate_imagewaits for the image and returns it directly; polling is only the fallback for slow jobs. - Live feedback. Progress updates carry the real stage reported by Codex and the elapsed time against what generations usually take on your machine.
- Editing.
edit_imagechanges an existing image — a previous result or any local file — and both tools accept reference images. - Cancellation.
cancel_imagestops a job and its Codex session immediately. - Usage awareness. Every result shows how much of your ChatGPT plan's Codex limit is used and when it resets, warns when you are close, and asks before a job would run on paid credits.
Why Pixmith? Codex can be signed in with your ChatGPT account, so image generation runs against your existing ChatGPT plan instead of a separate, metered image API key. If you already pay for ChatGPT, you get image generation in Claude for no extra cost — and Pixmith works just as well if your Codex is configured with an OpenAI API key instead.
ℹ️ Unofficial project. Pixmith is an independent, community tool. It is not affiliated with, endorsed by, or supported by OpenAI or Anthropic. "Codex", "ChatGPT", "OpenAI", "Claude", and "Anthropic" are trademarks of their respective owners.
⚠️ When using ChatGPT-subscription auth, image generation counts toward your ChatGPT plan's usage limits.
How it works
MCP client ──MCP(stdio)──▶ Pixmith ──spawn──▶ codex exec "$imagegen …" ──▶ gpt-image-2
▲ │
└──────────── PNG path + inline image ◀───────────┘
- The client calls
generate_image(oredit_image) with a prompt. Pixmith validates the request — size, output directory, input images — and queues a job. - Pixmith runs
codex exec --jsonwith a tightly-scripted prompt that tells Codex to call the built-inimage_gentool exactly once and replyDONE(orERROR: <reason>). Images to edit or reference are attached to that prompt. The agent is told not to copy files or run shell commands — Pixmith handles that. - Codex streams JSON events while it works. Pixmith turns them into stages (session started, rendering, finishing) and reports them as MCP progress notifications, together with the elapsed time and the typical duration of recent jobs.
- Pixmith trims the agent's overhead. For plain generations the image prompt is handed to the agent in a file, so its tool call stays a few lines long instead of retyping the whole prompt token by token. And as soon as the finished PNG is on disk, Pixmith stops Codex rather than waiting for the agent's closing turn. Together these took a long-prompt 1536×1024 generation from ~46s to ~34s; what remains is almost entirely OpenAI's render time.
- Codex writes the PNG to
$CODEX_HOME/generated_images/<session id>/. Pixmith takes the session id from Codex's event stream, copies that session's PNG into the requested output directory, and validates it is a real PNG. If no file was written (seen on Windows), it decodes the image from the base64 in Codex's output or the session's rollout log instead. - The same tool call returns the absolute path plus the image inline. MCP clients cap
the size of a tool result (Claude Desktop rejects anything over 1 MB) and these PNGs
are 2–3 MB, so the inline copy is a JPEG preview sized to fit, normally still at full
resolution up to a 2048px long edge. The full-quality PNG is always the file at the returned path. If the job
outlasts the wait window (~45s), the call returns a
job_idinstead and the client collects the image withget_image_result.
Because each job is matched to its own Codex session, concurrent jobs can never pick up each other's image.
No tokens or secrets are ever read, printed, or committed by Pixmith.
Authentication: ChatGPT subscription or API key
Pixmith just shells out to whatever codex you point it at, so it works with either
way of authenticating the Codex CLI:
- ChatGPT subscription (recommended, no API key): sign in to Codex with your ChatGPT account. Image generation is billed against your ChatGPT plan's limits.
- OpenAI API key: if your Codex CLI is configured to use an
OPENAI_API_KEY, generation is billed to your OpenAI API account instead. Pixmith does not require or read the key itself — it's Codex's own configuration.
Either way, Pixmith does not handle credentials directly.
Prerequisites
Pixmith runs on macOS, Windows, and Linux.
- The Codex CLI, via one of:
- the Codex desktop app (bundles the
codexbinary), or - a standalone
codexbinary on yourPATH.
- the Codex desktop app (bundles the
- Codex signed in — either with your ChatGPT account or configured with an
OpenAI API key (see above). Verify with
codex --versionand a quickcodex exec "hello". - Node.js ≥ 18.
Finding the Codex binary
Pixmith auto-detects the Codex binary in the common per-OS install locations and
otherwise falls back to whatever codex is on your PATH. If auto-detection
misses, set CODEX_BIN to the absolute path. To locate it:
| OS | Find it with | Typical location |
|---|---|---|
| macOS | which codex |
/Applications/Codex.app/Contents/Resources/codex (desktop app bundle), or ~/.local/bin/codex (standalone installer) |
| Windows | where codex (cmd) |
%LOCALAPPDATA%\Programs\codex\codex.exe, or %APPDATA%\npm\codex.cmd |
| Linux | which codex |
/usr/local/bin/codex, ~/.local/bin/codex |
If CODEX_BIN points at a file that no longer exists — for example Codex was
reinstalled somewhere else after you configured your MCP client — Pixmith falls back to
auto-detection instead of failing, and adds a Note: to each result so you can clean up
the stale setting.
Windows note: both a native
codex.exeand an npm-installedcodex.cmdshim work — Pixmith handles each. If you pointCODEX_BINat a.cmd/.bat, Pixmith runs it through the shell automatically. Use a full absolute path, and in JSON configs either use forward slashes (C:/Users/you/...) or escaped backslashes (C:\\Users\\you\\...).
Install
Every route needs the Codex CLI or the Codex desktop app, signed in with your ChatGPT account (see prerequisites).
Claude Desktop: one-click bundle
Download pixmith-<version>.mcpb from the
releases page and open it (or drag it
into Claude Desktop's Settings → Extensions). Claude Desktop shows Pixmith's
settings, all optional:
| Setting | What it does |
|---|---|
| Codex binary | Leave empty to find Codex automatically. |
| Image folder | Where images go. Empty: Pictures/Pixmith in your home folder. |
| Other folder images may be saved in | When set, Claude may save only into this folder or the image folder (PIXMITH_ALLOWED_DIRS). |
| Images at once | How many images may render at the same time (default 1). |
| Delete Codex's duplicate copies | Off by default. When on, Codex's own copy of each image is deleted once Pixmith's is saved (details). |
To build the bundle yourself: npm run bundle writes dist/pixmith.mcpb (it installs
only the runtime dependencies into a temporary folder, so dev tools never end up in it).
Claude Code: plugin
In Claude Code, run:
/plugin marketplace add glassd/Pixmith
/plugin install pixmith@pixmith
On Claude Code 2.1.275 or later this works in one step:
/plugin install pixmith --marketplace glassd/Pixmith
The plugin bundles the MCP server and the two skills. Claude Code installs
the npm dependencies itself, so you only need Node.js and a signed-in Codex. Images are
saved to ~/Pictures/Pixmith unless you set PIXMITH_OUTPUT_DIR in your environment.
Pixmith's timing history lives in the plugin's data folder, so it survives updates.
If you registered Pixmith by hand before, remove that entry (claude mcp remove pixmith)
so you don't run two copies.
Any MCP client: npm
Run it with npx; no clone needed. In Claude Desktop's claude_desktop_config.json
(or any client's mcpServers block):
{
"mcpServers": {
"pixmith": { "command": "npx", "args": ["-y", "pixmith"] }
}
}
In Claude Code, prefer the plugin, which adds the skills too; for
the server alone: claude mcp add pixmith --scope user -- npx -y pixmith.
From source
git clone https://github.com/glassd/Pixmith.git
cd Pixmith
npm install
then register it with the path
to src/index.js.
Where files go. Run from a git checkout, Pixmith keeps images in images/ and its
own state in .pixmith/ inside the project, as before. Installed as a bundle or from
npm, the code sits in a folder you never open, so images go to Pictures/Pixmith in
your home folder (or ~/Pixmith without a Pictures folder), and state to
~/Library/Application Support/Pixmith (macOS), %LOCALAPPDATA%\Pixmith (Windows) or
~/.local/state/pixmith (Linux). As a Claude Code plugin, images go to
~/Pictures/Pixmith and state to the plugin's data folder. PIXMITH_OUTPUT_DIR and
PIXMITH_STATE_DIR override all of these.
Run / smoke test
The server speaks MCP over stdio, so normally your MCP client launches it. Running it directly just verifies it boots:
npm start
Generate a test image directly through the engine (bypasses the MCP protocol):
npm run smoke # "a red circle on a white background" @ 1024x1024
node scripts/smoke-test.js "a tabby cat astronaut" 1536x1024
node scripts/smoke-test.js "make the helmet gold" auto /abs/path/to/cat.png # edit
A successful run prints JSON with the saved path. Images land in ./images/ by
default.
Tests (no Codex needed — a fake Codex in fixtures/ stands in for it):
npm test
CI runs the same suite on Linux for Node 18, 20, 22 and 24, and on macOS and Windows for Node 24.
Lint and formatting (ESLint for correctness, Prettier for layout; both need Node 20.19+):
npm run lint # ESLint
npm run format # rewrite files with Prettier
npm run format:check # what CI checks
The tools
A generation is a Codex agent session, so it takes roughly 30–40s (edits about twice
that) — close to the per-request timeout some MCP clients enforce. Pixmith therefore
never blocks a single call for longer than the wait window (PIXMITH_POLL_WAIT_MS,
default 45s). A typical generation fits inside it, so the usual flow is one tool
call that returns the image. If the window closes while Codex has already finished and
the image is only being collected, the call waits up to 8s more (never beyond 58s in
total) rather than costing another round trip. Slower jobs fall back to a job_id plus
get_image_result. The assistant drives all of this automatically.
generate_image — make an image
| Param | Type | Required | Description |
|---|---|---|---|
prompt |
string | ✅ | Text description of the image. |
size |
string | ❌ | auto, a shortcut 1K/2K/4K, or explicit WIDTHxHEIGHT (e.g. 1024x1024, 1536x1024, 3840x2160). See size limits. Default 1024x1024. |
reference_images |
string[] | ❌ | Up to 4 absolute paths of images (PNG, JPEG, WebP, GIF) to use as style, composition or subject references. |
background |
string | ❌ | auto (default: transparent only if the prompt asks for it), transparent (a PNG with an alpha channel, the subject alone, for logos, icons and stickers) or opaque. See backgrounds. |
variants |
integer | ❌ | 1–4, default 1. How many alternative images to make. Each is a full generation against the plan's usage. See variants. |
filename |
string | ❌ | File name for the PNG, without a folder (e.g. hero-banner). Cleaned to letters, digits, ., _ and -; never overwrites, adding -2, -3… instead. Default: made from the prompt. |
output_dir |
string | ❌ | Absolute directory to save into. Defaults to Pixmith's images/ folder. |
wait |
boolean | ❌ | Default true: wait up to the wait window and return the image directly. false returns the job_id at once — handy for starting several jobs back to back. |
use_credits |
boolean | ❌ | Only matters once the plan limit is used up: confirms that you agreed to continue on paid credits. See plan usage and credits. |
Invalid sizes, relative output_dir paths and unreadable input images are rejected
here, before any Codex session starts. If more than PIXMITH_MAX_CONCURRENT jobs are in
flight the new one is reported as status: queued with its position.
edit_image — change an existing image
| Param | Type | Required | Description |
|---|---|---|---|
image |
string | ✅ | Absolute path of the image to edit — a previous Pixmith result or any local PNG, JPEG, WebP or GIF (max 20 MB). |
prompt |
string | ✅ | What to change. Say what must stay the same, e.g. "make the sky stormy; keep everything else unchanged". |
reference_images |
string[] | ❌ | Extra images to borrow style or content from (up to 4 images in total). |
size |
string | ❌ | As above. Defaults to auto, which keeps the source's aspect ratio. |
background, variants, filename, output_dir, wait, use_credits |
❌ | As for generate_image. |
The source file is never modified; the edit is saved as a new PNG. Every finished result
ends with the exact edit_image call that would refine it, so iterating is a one-liner
for the assistant.
pixmith_status — check the setup
No parameters. Checks everything that decides whether an image can be made, without making one (so it uses no plan quota), and says what to do about each problem:
Pixmith 0.6.1: ready to make images.
Codex: version 0.46.0 at /opt/homebrew/bin/codex
Signed in: yes, with a ChatGPT account
Plan usage: 12% of the 5-hour limit (resets at 18:40), 3% of the weekly limit (resets Mon at 09:00).
Output folder: /Users/you/Pixmith/images (writable)
Jobs: 0 running, 0 queued
Settings: up to 1 job at a time, 45s wait window, 300s timeout, sandbox workspace-write, credits policy "ask"
Running on Node 22.12.0 (darwin).
It runs codex --version and codex login status (neither starts a session) and reads
the latest plan-usage figures. Problems it reports: Codex not found, not signed in, the
plan's limit reached, an unwritable output folder. Warnings cover settings that were
ignored, a stale CODEX_BIN, and a Codex signed in with an API key, which bills
images to that API account instead of the ChatGPT plan. Pixmith never reads Codex's
credentials: with a Codex too old to have login status, it only checks whether the
credentials file exists.
Backgrounds
background: "transparent" asks for a PNG with an alpha channel: the subject alone, with
no backdrop, floor or shadow. The image tool only takes a prompt, so this is an
instruction to the model rather than a switch, and it does not always follow it. Pixmith
therefore checks the PNG it gets back and says so: Background: transparent (the PNG has an alpha channel)., or a note that the background came out opaque, so you can retry
(has_alpha in structured results). An inline JPEG preview cannot
show transparency, so transparent areas look white there; the PNG on disk keeps them.
background: "opaque" rules transparency out even when the prompt mentions it.
Variants
variants: 3 makes three alternative images from one prompt. Each is its own Codex
session and job, so each counts toward the plan's usage like a separate request, and
they run one after another unless PIXMITH_MAX_CONCURRENT is raised. The call waits for
them within the usual window and returns all that are ready, each with its path and
job_id and the inline images side by side (sharing the client's size limit, so the
previews are smaller). Any still running are collected with get_image_result and their
own job_id. With a filename, variants are numbered: logo-1.png, logo-2.png, …
get_image_result — collect a slower job
| Param | Type | Required | Description |
|---|---|---|---|
job_id |
string | ❌ | The job to fetch. Optional only when a single job could be meant (see below); pass it always. |
Waits up to the wait window, then returns. While the job is waiting for a slot or still
rendering it returns status: queued or status: running with the current stage,
elapsed time and an estimate of what is left; the assistant simply calls it again until
status: done. Results can be fetched more than once, so an image is never lost to a
client-side timeout. A finished image's job_id keeps working afterwards, even after
Pixmith restarts (it is looked up in the image history).
Without a job_id. An MCP client such as Claude Desktop runs one Pixmith server for
all its conversations, and Pixmith cannot tell them apart, so "the latest job" may be
another conversation's. Without a job_id, get_image_result therefore picks a job only
when exactly one could be meant: the only job whose result has not been returned yet
(queued, running, or finished after its call timed out), or failing that the only job that
finished in the last 10 minutes. The result then says which prompt it picked. When several
jobs qualify it picks none and fails with [ambiguous_job], listing each candidate's
job_id, status, age and first words of its prompt (also as candidates in the
structured output).
cancel_image — stop a job
| Param | Type | Required | Description |
|---|---|---|---|
job_id |
string | ❌ | The job to cancel. Optional only when a single job is queued or running. |
A queued job is dropped; a running job's Codex session is killed at once, so it stops
using your ChatGPT quota. Without a job_id it cancels the only queued or running job;
with several, it cancels nothing and fails with [ambiguous_job], listing them. Pixmith also stops every running session when the MCP client
disconnects.
list_images — find earlier images
| Param | Type | Required | Description |
|---|---|---|---|
limit |
integer | ❌ | How many to return, 1–50. Default 10. |
query |
string | ❌ | Only images whose prompt contains this text (case-insensitive). |
mode |
string | ❌ | generate or edit: only generated, or only edited, images. |
Lists finished images newest first, each with its time, mode, size, prompt, path, the
image an edit was made from, and its job_id, so you can say "edit the fox picture from
earlier" and the assistant can find it. It covers every output folder, and leaves out
images that have been deleted since.
The list comes from Pixmith's image history, history.jsonl in its state folder
(PIXMITH_STATE_DIR, default .pixmith/), which gets one line per finished image and
keeps the newest 1,000 (it is trimmed back to 1,000 once it passes 1,500). It holds your prompts; delete the file to clear the history.
Servers sharing a state folder (e.g. Claude Desktop and Claude Code) share the history.
Pixmith MCP questions
How do I add Pixmith MCP to Claude Code?
Run claude mcp add pixmith -- npx -y pixmith in your terminal. Add --scope user to make it available in every project.
How do I add Pixmith MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Pixmith MCP provide?
It exposes 6 tools, including generate_image, edit_image, get_image_result, cancel_image, list_images.
Can Pixmith edit existing images?
Yes, the edit_image tool allows you to change an existing image, whether it is a previous result or a local file.
How does Pixmith handle large image files in MCP clients?
Since some clients like Claude Desktop reject files over 1 MB, Pixmith provides a JPEG preview inline while returning the full-quality PNG as a file path.