Pixara
Pixara is an MCP server that gives LLMs direct access to OpenRouter's Image API for generating, editing, and exploring AI image models through 4 tools:
Generate images (
pixara_generate_image): Create images from text prompts using any OpenRouter image model (e.g., FLUX, GPT Image, Stable Diffusion), with control over resolution, aspect ratio, quality, output format, background, compression, and seed. Results are saved to disk and file paths are returned.Edit/transform images (
pixara_edit_image): Perform image-to-image edits by providing one or more reference images (local file path, remote URL, or raw base64) alongside a text prompt. File reading and encoding are handled automatically.List available models (
pixara_list_image_models): Browse OpenRouter's image model catalog with filtering by provider, name, and capability flags (img2img, streaming, transparent background support). Supports pagination and returns results in Markdown or JSON.Inspect model details (
pixara_get_model_details): Retrieve per-provider pricing, supported parameters (with allowed values/ranges), and passthrough options for a specific model — useful for confirming compatibility before making a generation call.
All image operations are billed through OpenRouter; listing and model details are free.
Pixara MCP Server
An MCP server that gives LLMs direct access to OpenRouter's Image API to generate images, edit/transform existing ones, and browse the model catalog, all through 4 tools.
I built this because I saw that OpenRouter announced a unified Image API that gives you one endpoint to use image generation and image editing models like GPT Image, Nano Banana, Flux, etc. Use the pixara_list_image_models tool to see the full, current models list from OpenRouter.
Features
Generate images from a text prompt against any OpenRouter image model
Edit/transform images (img2img) using a local file, a URL, or raw base64 as the reference, and the tool reads and encodes local files for you
List models with filtering by provider, name, and capability (img2img, streaming, transparent background), plus pagination
Inspect a model's endpoint details: per-provider pricing, supported parameters, and allowed passthrough options — before you spend a call on something it doesn't support
Generated images are decoded and saved to disk, so responses stay small and a file path is returned
Clear error messages for common failure modes: bad/conflicting params, invalid key, insufficient credits, rate limits, provider unavailable
Related MCP server: openrouter-image-gen-mcp
Quick start (recommended)
Pixara is published on npm as @pinkpixel/pixara-mcp.
The easiest way to use it is via npx — no install, no cloning, no build step.
Add this to your MCP config (claude_desktop_config.json) for Claude Desktop, or your MCP client's .json config file:
{
"mcpServers": {
"pixara": {
"command": "npx",
"args": ["-y", "@pinkpixel/pixara-mcp"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
"OPENROUTER_IMAGE_OUTPUT_DIR": "/absolute/path/to/wherever/you/want/images"
}
}
}
}Restart the client and you should see the four pixara_* tools available. npx -y fetches
and caches the package on first run, so there's nothing to update manually. New versions get
picked up automatically.
Configuration
Variable | Required | Description |
| Yes | Get one at openrouter.ai/keys |
| No | Where generated images are saved. Defaults to |
The server just reads these from process.env — there's no .env file loading built in.
Whether you're running via npx or from source, set these in the env block of your MCP
config, as shown above. OPENROUTER_IMAGE_OUTPUT_DIR is optional — leave it out and images
save to ./pixara-images relative to wherever the server process runs; set it to an
absolute path if you want a predictable location regardless of the client's working directory.
Installing from source
For local development, or if you'd rather not rely on npx:
Requires Node.js 18+.
git clone https://github.com/sizzlebop/pixara-mcp.git
cd pixara-mcp
npm install
npm run buildThen point your MCP config at the built file instead of npx:
{
"mcpServers": {
"pixara": {
"command": "node",
"args": ["/absolute/path/to/openrouter-image-mcp/dist/index.js"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
"OPENROUTER_IMAGE_OUTPUT_DIR": "/absolute/path/to/wherever/you/want/images"
}
}
}
}Tools
pixara_generate_image
Text-to-image. Required: model, prompt. Optional: n, resolution, aspect_ratio,
size, quality, output_format, background, output_compression, seed,
provider_options, output_dir, filename_prefix.
Don't combine size with resolution/aspect_ratio — pick one or the other, the tool will
reject the call with a clear message if you mix them.
pixara_edit_image
Same params as generate_image, plus a required input_references array. Each entry is one
of:
{ "source": "file", "path": "/path/to/photo.png" }
{ "source": "url", "url": "https://example.com/photo.jpg" }
{ "source": "base64", "data": "<base64>", "media_type": "image/png" }pixara_list_image_models
Read-only, free (no image billing). Filter by filter (substring), provider, or capability
booleans (supports_img2img, supports_streaming, supports_transparent_background).
Paginated with limit/offset.
pixara_get_model_details
Read-only, free. Pass a model slug, get back per-provider pricing and exactly which
parameters/passthrough options that provider supports. Worth calling before you use
provider_options, since unsupported params get silently dropped or rejected by the API.
How it decides where to save images
Every generate/edit call decodes the base64 image(s) OpenRouter returns and writes them to
OPENROUTER_IMAGE_OUTPUT_DIR (or a per-call output_dir override), named
{prefix}-{timestamp}-{index}.{ext}. The extension follows output_format, except for
vector output (Recraft's SVG models), which is detected via the response's media_type and
written as .svg regardless of what output_format was requested.
Limitations
No SSE streaming support yet (see Roadmap)
Model capabilities vary a lot by provider, and OpenRouter's catalog moves fast — always trust
pixara_list_image_models/pixara_get_model_detailsover any hardcoded listThis is new — OpenRouter's Image API has only been out a couple of weeks, so expect model IDs and params to shift over time
License
Apache 2.0 — see LICENSE.
Made with 💖 by Pink Pixel
Available Tools
4 toolspixara_edit_imageEdit Image (OpenRouter)A
Edit or transform an existing image using a text prompt and one or more reference images, via any image-to-image-capable model on OpenRouter.
This calls OpenRouter's Image API with input_references and saves the resulting image(s) to disk. Reference images can be a local file path, a remote URL, or raw base64 — this tool handles reading/encoding local files itself, so you never need to pre-encode anything.
Args:
model (string): Must support image-to-image, e.g. 'openai/gpt-image-1' or 'bytedance-seed/seedream-4.5'. Check with pixara_get_model_details first if unsure.
prompt (string): Instruction describing the desired edit/transformation.
input_references (array, required, 1+): Each entry is one of: { source: "file", path: "/abs/or/relative/path.png" } { source: "url", url: "https://example.com/photo.jpg" } { source: "base64", data: "", media_type: "image/png" }
n, resolution, aspect_ratio, size, quality, output_format, background, output_compression, seed, provider_options, output_dir, filename_prefix: same meaning as in pixara_generate_image.
Returns: Markdown summary listing each saved file's path, media type, size in bytes, and the total cost charged by OpenRouter for the request.
Examples:
Use when: "Make this photo look like a watercolor painting" with a local file path
Use when: "Remove the background from this product photo" with a URL reference
Don't use when: there's no reference image at all (use pixara_generate_image)
Error Handling:
"Could not read reference image" -> check the file path is correct and readable
"Bad request" -> the chosen model may not support img2img; verify with pixara_get_model_details
"Insufficient OpenRouter credits" -> add credits at https://openrouter.ai/credits
Inputs: model (required), prompt (required), input_references (required), n, +11 more.
pixara_generate_imageGenerate Image (OpenRouter)A
Generate an image from a text prompt using any image model available on OpenRouter.
This calls OpenRouter's dedicated Image API (not chat completions) and saves the resulting image(s) to disk, returning the file path(s), model used, and cost. It does NOT edit or use reference images — for image-to-image/editing, use pixara_edit_image instead.
Args:
model (string): OpenRouter model slug, e.g. 'black-forest-labs/flux-1.1-pro' or 'openai/gpt-image-1'. Use pixara_list_image_models to discover options.
prompt (string): Text description of the desired image.
n (number, 1-10, default 1): Number of images to generate. Not all models support n > 1.
resolution ('512'|'1K'|'2K'|'4K', optional): Resolution tier.
aspect_ratio (string, optional): e.g. '16:9', '1:1'. Don't combine with 'size'.
size (string, optional): Convenience tier or explicit dimensions. Don't combine with resolution/aspect_ratio.
quality ('auto'|'low'|'medium'|'high', optional)
output_format ('png'|'jpeg'|'webp', default 'png')
background ('auto'|'transparent'|'opaque', optional): 'transparent' requires png/webp.
output_compression (0-100, optional): webp/jpeg only.
seed (number, optional): For deterministic generation where supported.
provider_options (object, optional): Provider-specific passthrough params. Check pixara_get_model_details first for allowed keys.
output_dir (string, optional): Where to save images (default: OPENROUTER_IMAGE_OUTPUT_DIR).
filename_prefix (string, optional): Prefix for saved filenames.
Returns: Markdown summary listing each saved file's path, media type, size in bytes, and the total cost charged by OpenRouter for the request.
Examples:
Use when: "Generate a picture of a red panda astronaut" -> model + prompt only
Use when: "Make a transparent-background product shot" -> background='transparent', output_format='png'
Don't use when: you have a reference image to transform (use pixara_edit_image)
Error Handling:
"Insufficient OpenRouter credits" -> add credits at https://openrouter.ai/credits
"Bad request" / conflicting params -> re-check with pixara_get_model_details
"Rate limited" -> wait and retry
Inputs: model (required), prompt (required), n, seed, +10 more.
pixara_get_model_detailsGet Model Details (OpenRouter)ARead-onlyIdempotent
Get per-provider pricing, supported parameters, and passthrough options for one OpenRouter image model.
This is a read-only, no-cost call. Use it before pixara_generate_image / pixara_edit_image to confirm exactly which parameters a model/provider supports and what it costs — unsupported parameters are silently ignored or rejected by the API, so checking first avoids wasted/failed calls.
Args:
model (string, required): OpenRouter model slug, e.g. 'black-forest-labs/flux.2-pro'.
response_format ('markdown'|'json', default 'markdown').
Returns: Per-provider breakdown: pricing (billable type, unit, price, tier/variant), supported parameter descriptors (enum values, numeric ranges, or plain booleans), and any allowed_passthrough_parameters for use with the generate/edit tools' provider_options field.
Examples:
Use when: "How much does flux.2-pro cost and what steps/guidance params does it take?"
Use when: "Does gpt-image-1 support transparent backgrounds on this provider?"
Don't use when: browsing across many models (use pixara_list_image_models instead)
Error Handling:
"Resource not found" / empty endpoints -> the model id may be wrong; verify with pixara_list_image_models
Inputs: model (required), response_format.
pixara_list_image_modelsList Image Models (OpenRouter)ARead-onlyIdempotent
List image-generation models available on OpenRouter, with filtering and pagination.
This is a read-only, no-cost call (no image is generated). Use it to discover model IDs before calling pixara_generate_image or pixara_edit_image, or to find models with a specific capability.
Args:
filter (string, optional): Case-insensitive substring match against model id or name.
provider (string, optional): Restrict to models whose id starts with this prefix, e.g. 'openai', 'black-forest-labs'.
supports_img2img (boolean, optional): Only models that accept input_references.
supports_streaming (boolean, optional): Only models that support SSE streaming.
supports_transparent_background (boolean, optional): Only models supporting transparent backgrounds.
limit (number, 1-100, default 30), offset (number, default 0): Pagination.
response_format ('markdown'|'json', default 'markdown').
Returns: For JSON: { total, count, offset, models: [...], has_more, next_offset? } For Markdown: a heading per model with id, description, and supported parameter names.
Examples:
Use when: "What image models can do transparent backgrounds?" -> supports_transparent_background=true
Use when: "Show me FLUX models" -> filter='flux'
Don't use when: you already know the exact model id (skip straight to generate_image)
Inputs: limit, filter, offset, provider, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: generation, editing, model details, and model listing. There is no overlap or ambiguity.
All tools follow a consistent 'pixara_verb_noun' snake_case pattern, making them predictable and easy to navigate.
With 4 tools, the server is well-scoped, covering the essential image generation, editing, and model exploration without unnecessary or missing tools.
The tool set covers the full lifecycle: discovery (list and get details), generation (text-to-image), and editing (image-to-image). No obvious gaps for the stated purpose.
Maintenance
Related MCP Connectors
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for Qwen Image 3 AI image generation
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
Generate AI images and videos from any compatible MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server that wraps OpenAI's image generation and editing APIs, enabling text-to-image and image-to-image operations via tools.292 npm37ISC
- AlicenseAqualityDmaintenanceMCP server for generating images using OpenRouter API, supporting models like Gemini 2.5 Flash. Enables image generation with flexible options like saving to local files.2Do What The F*ck You Want To Public
- AlicenseNot gradedqualityDmaintenanceMCP server for generating and editing images using OpenRouter API, with support for multiple models and dynamic model discovery. Runs in Docker and integrates with Claude Desktop via stdio transport.MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables local AI agents to generate images and videos through the OpenRouter API, manage a browsable media library, and track generation costs.11MIT