This server lets an agent generate and edit images through Pixfaro's paid image-model API and check account details.
Generate images from a text prompt, choosing a model (default nano-banana-2) and optional aspect ratio; returns a hosted image URL, cost, and balance.
Edit images by passing a previous img_… id with a natural-language instruction; optionally reshape the image with a new aspect ratio.
List available models with pricing, latency, and use-case guidance.
Get the current prepaid balance in USD.
No base64 payloads: replies use long-term hosted URLs to keep agent context small.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Pixfaro MCP generate a cozy cabin in snowy mountains, 16:9"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
One MCP connection, one prepaid balance, every major image model — Nano Banana,
Gemini today, GPT Image next (visible as "coming soon" in list_models).
Pixfaro holds the provider accounts, keys, retries and format differences;
your agent just asks for an image.
Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP client.
The remote server is the easiest path: paste one URL, sign in with your Pixfaro account in the browser window that opens. No API key in any file.
Claude (claude.ai / Claude Desktop, any plan): Settings → Connectors →
Add custom connector → URL https://mcp.pixfaro.com/mcp → sign in.
(Team/Enterprise: an org Owner adds it once under Organization settings →
Connectors → Custom → Web.)
Cursor: Add to Cursor →
— or Cursor Settings → MCP → Add new MCP server (type URL, address
https://mcp.pixfaro.com/mcp); Cursor runs the OAuth flow itself.
ChatGPT (Pro/Plus/Business/Edu): Settings → enable Developer mode
(connectors live under Plugins since the July 2026 rename, formerly
Connectors → Advanced) → add a custom connector with URL
https://mcp.pixfaro.com/mcp, OAuth.
Related MCP server: MCP Banana Image
Get an API key at pixfaro.com and top up (no subscription).
Add the server to your MCP client config:
{
"mcpServers": {
"pixfaro": {
"command": "npx",
"args": ["-y", "@pixfaro/mcp"],
"env": { "PIXFARO_KEY": "pf_live_…" }
}
}
}Ask your agent for an image. That's it.
For Claude Code:
claude mcp add pixfaro -e PIXFARO_KEY=pf_live_… -- npx -y @pixfaro/mcpClients that speak streamable HTTP can also take the remote form in the same file — no key, OAuth on first use:
{ "mcpServers": { "pixfaro": { "url": "https://mcp.pixfaro.com/mcp" } } }
``` Clients
without OAuth can pass an API key instead: `Authorization: Bearer pf_live_…`.
## Tools
| Tool | What it does |
|---|---|
| `generate_image` | prompt → hosted image URL (+cost and balance in the reply) |
| `edit_image` | natural-language edit of a previous generation by its `img_…` id |
| `list_models` | models with price, latency, and what each is best for |
| `render_template` | typeset card (quote/post) from a template — $0.02, ~2 s, sharp type · *remote server; npx parity coming in 0.2* |
| `list_templates` | card templates with slots, style axes and exact prices · *remote server* |
| `upload_asset` | upload a PNG/JPEG (≤5 MB) as a reusable asset (e.g. a card avatar) · *remote server* |
| `get_balance` | current prepaid balance |
Replies carry a hosted URL, never base64 — your agent's context stays small.
Both generation tools accept `aspect_ratio` (e.g. `"16:9"`, `"9:16"`). Edits
keep the source image's shape when you omit it — pass one only to reshape.
## CLI
The same package family ships an unscoped CLI for scripts, CI, and pipelines:
```bash
export PIXFARO_KEY=pf_live_…
npx pixfaro gen "a lighthouse at night, minimal flat style" -a 16:9 -o cover.png
npx pixfaro models
npx pixfaro balance
npx pixfaro edit img_8f2a… "make the sky darker" -o v2.pngVariable | Meaning |
| your API key ( |
| endpoint override (default |
The thin open client over the Pixfaro API: the MCP server (@pixfaro/mcp) and
the pixfaro CLI share one HTTP client. The balance/provider layer lives
behind api.pixfaro.com — this code is intentionally
small enough to read before you hand it a key.
MIT © Pixfaro
Edit a previously generated image with a natural-language instruction (e.g. "make the sky darker", "remove the text"). Pass the img_… id returned by generate_image.
| Name | Required | Description | Default |
|---|---|---|---|
| image | Yes | The img_… id of a previous generation | |
| model | No | Model id from list_models | nano-banana-2 |
| instruction | Yes | What to change; everything else stays the same | |
| aspect_ratio | No | omit to keep the source image's shape; e.g. "16:9" to reshape |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure. It mentions that the instruction changes only specified aspects, implying non-destructive edits to the rest of the image, but does not detail other behaviors like whether the original image is preserved or if there are rate limits or authentication requirements. The description adds some context but falls short of fully disclosing the tool's side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded with purpose and example instructions. Every word adds value without repetition. It is concise and easily scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (editing with optional parameters) and that the schema fully documents all parameters, the description covers the key contextual points: the input source and example usage. No output schema exists, but the description does not need to explain return values. The main gap is the absence of explicit behavioral notes (like original image preservation), but the description is sufficient for an agent to use the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters, covering schema descriptions, including the instruction's semantics (e.g., 'what to change'). The parameter descriptions are self-explanatory, and the 'aspect_rating' schema is adequately described. Since schema coverage is 100%, the description adds no extra semantic detail beyond the schema. The baseline is 3 because while the schema is self-sufficient, the description could add value by, for example, clarifying that the 'model' is optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: editing a previously generated image using a natural-language instruction. It distinguishes itself from the sibling tool generate_image by focusing on editing existing images rather than creating new ones, and provides concrete examples of instructions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (edit existing images) and implies it's an alternative to generate_image for modifications. It also clarifies that the input must be an img_… id from generate_image, providing clear context. However, it does not explicitly state when not to use it, like when generating a new image.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an image from a text prompt. Returns a hosted image URL (valid long-term) plus cost and balance. Pick a model with list_models; nano-banana-2 is the general-purpose default.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Model id from list_models | nano-banana-2 |
| prompt | Yes | What to draw. Be specific about style, mood, and composition. | |
| aspect_ratio | No | e.g. "1:1", "16:9", "9:16" | 1:1 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well by disclosing the return format (hosted image URL valid long-term) and the side-effect of cost/balance deduction. It also hints at model selection behavior, adding value beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core action and output, and no wasted words. Every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple generation tool with 3 parameters and no output schema, the description covers the purpose, output, model selection, and cost/balance. It lacks explicit error handling or rate-limit info, but these are likely unnecessary given the tool's scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds minor context for the model parameter (default and source) but doesn't elaborate beyond what the schema already states for prompt or aspect_ratio.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Generate an image from a text prompt' with a specific verb and resource, and differentiates from siblings like edit_image, list_models, and get_balance by focusing on creation and returning a hosted URL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent to use list_models for model selection and notes nano-banana-2 as the default, providing useful workflow context. It doesn't explicitly exclude alternatives, but the sibling names (edit_image, get_balance) imply distinct use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the current prepaid balance in USD.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. 'Show' indicates a read-only operation with no side effects, and 'current prepaid balance in USD' specifies what is returned. It does not mention error cases or exact response format, but for a zero-parameter getter this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and object. Every word adds value: 'current,' 'prepaid,' 'balance,' and 'USD.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no annotations, and no output schema, the description adequately covers tool selection and invocation. It could explicitly state the return type (e.g., numeric value), but the phrase 'balance in USD' makes this largely self-evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts no parameters, so there are no parameter semantics to clarify. The baseline of 4 applies because no compensation in the description is needed for undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') and a clear resource ('current prepaid balance in USD'), making the tool's function unambiguous. It also distinguishes itself from the image-generation/editing and model-list sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies that the tool should be used when an agent needs to check the current prepaid balance. No alternatives or exclusions are needed because the sibling tools are unrelated in function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available image models with pricing, latency, and what each is best for.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly states the operation is a read-only listing and specifies what data is returned. It does not discuss caching, authentication, or availability nuance, but for a zero-parameter list tool these are minor omissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and resource, then adds the key output dimensions. Every word earns its place, with no filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, zero parameters, and absent output schema, the description reasonably covers what an agent needs to know: what is listed and what attributes are provided. It could be slightly more explicit about the output format or whether availability is account-specific, but overall it is complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides no parameter semantics to augment. The description appropriately focuses on the output (pricing, latency, best-for) rather than inputs, matching the baseline of 4 for parameter-less tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('available image models') and names exact attributes (pricing, latency, best-for). This clearly distinguishes it from the sibling tools, which generate or edit images or check balance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you need model information before choosing a model, but it does not explicitly state when to use it versus alternatives or mention any exclusions. Sibling names suggest the context, but the description itself offers no direct usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2edit_imagegenerate_imageget_balancelist_modelsScored across 4 tools
Each tool has a clearly distinct action-object pair: generating an image, editing an image, listing models, and checking balance. There is no overlap in purpose, so an agent can confidently choose the right tool.
All four tools follow the same snake_case verb_noun pattern: generate_image, edit_image, list_models, get_balance. The naming is uniform and predictable.
Four tools is well-scoped for an image-generation server, covering core generation, editing, model discovery, and account balance. Each tool earns its place without unnecessary bloat.
The core workflow is covered end-to-end: choose a model, generate, edit, and check spending. A minor gap is the lack of image history/retrieval, but that does not break the primary generation workflow.
MCP server for NanoBanana AI image generation and editing
MCP server for Qwen Image 3 AI image generation
MCP server for Pixapi: check live credit pricing and balance, then generate images and video.
MCP server for Midjourney AI image generation and editing