Skip to main content
Glama
runapi-ai

Nano Banana MCP Server

by runapi-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Why This Package?

@runapi.ai/nano-banana-mcp is a focused Model Context Protocol server for the Nano Banana model line on RunAPI. It gives MCP-compatible assistants direct access to 2 endpoints and 5 model variants without loading the full RunAPI catalog.

Use this per-model server when an agent should stay scoped to Nano Banana. Use @runapi.ai/mcp when one assistant should discover every RunAPI model line.

Related MCP server: GPT Image MCP Server

Install

Add it to Claude Code:

claude mcp add nano-banana -s user -- npx -y @runapi.ai/nano-banana-mcp

Use project scope when the server should be shared with a repository:

claude mcp add nano-banana -s project -- npx -y @runapi.ai/nano-banana-mcp

Codex, Cursor, Windsurf, VS Code, Roo Code, and other MCP hosts can use the same stdio command:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "@runapi.ai/nano-banana-mcp"]
    }
  }
}

check_pricing works before sign-in. For task creation and status polling, ask your assistant to call the login tool. It opens a browser login and saves credentials to ~/.config/runapi/config.json, the same file used by runapi login. Headless and CI hosts can still set RUNAPI_API_KEY before starting the MCP host.

Ready-made examples are in examples/ for Claude, Cursor, Windsurf, VS Code, and Roo Code.

Tools

Tool

Auth

Purpose

edit_image

Yes

Create a Nano Banana edit image task and optionally wait for a terminal status. Returns the task id, status, and output URLs.

text_to_image

Yes

Create a Nano Banana text to image task and optionally wait for a terminal status. Returns the task id, status, and output URLs.

get_task

Yes

Fetch the current status and latest payload for an existing task.

check_pricing

No

Look up current pricing for a Nano Banana model and endpoint.

Models

Nano Banana covers 5 model variants across 2 endpoints. Each tool accepts the models listed for it:

Tool

Models

edit_image

nano-banana-2-lite, nano-banana-edit

text_to_image

nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro

Model availability can change between releases. Use check_pricing or the Nano Banana model page for the current catalog view.

Agent Prompts

Ask your assistant in natural language; it can inspect pricing, create the task, and return the task id plus output URLs.

Create a task

Run a Nano Banana edit image task with RunAPI.

The assistant can call check_pricing, then edit_image, and return the task id, status, and output URLs.

Submit without waiting

Create the task but don't wait for it to finish.

The assistant calls the create tool with wait: false and returns the task id. Check on it later with get_task.

Check pricing before creating

Check current Nano Banana pricing, then create the task if it matches my request.

The assistant calls check_pricing and can link to the Nano Banana model page for the canonical catalog entry.

Configuration

The server resolves auth in this order:

  1. RUNAPI_API_KEY environment variable, useful for headless and CI hosts

  2. ~/.config/runapi/config.json, created by the MCP login tool or runapi login

  3. No key, which still allows check_pricing

The config file is normally managed by login. A pre-provisioned headless config can use:

{
  "apiKey": "your_runapi_key"
}

Do not commit real API keys.

Links

Resource

URL

Nano Banana model page

https://runapi.ai/models/nano-banana

npm package

@runapi.ai/nano-banana-mcp

GitHub repository

runapi-ai/nano-banana-mcp

RunAPI MCP overview

runapi.ai/mcp

RunAPI docs

runapi.ai/docs

License

Licensed under the Apache License, Version 2.0.

Available Tools

5 tools
check_pricingC

Look up RunAPI pricing for the nano-banana model line.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoModel slug. Defaults to the line's primary model.
actionNoEndpoint name. Defaults to the endpoint that offers the model.

TDQS

C2.9/5.0
Behavior2/5

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 implies a read-only lookup but says nothing about permissions, whether pricing is live or cached, currency/units, or what the response shape is for a zero-argument-required call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler, and the resource is named before the scope. It is efficient, though arguably under-sized for a tool with no annotations and no output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations, no output schema, and no return-value description, an agent cannot know what 'pricing' means in practice (per-image cost, tiers, token rates). For a lookup tool this is a meaningful gap that the single sentence does not close.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with both enum parameters and their defaults documented in the schema, so the baseline is 3. The description adds only that the lookup spans a 'model line,' which slightly informs the model parameter but provides no syntax or default detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Look up') and resource ('RunAPI pricing') scoped to the nano-banana model line, so an agent knows exactly what it retrieves. It does not, however, explicitly differentiate itself from the sibling tools (edit_image, text_to_image) that consume that pricing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this versus the sibling generation tools, no mention of prerequisites, and no indication of when the information would be stale or unnecessary. An agent must infer that this is a pre-flight/cost-check step.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_imageC

Create a Nano Banana task on RunAPI (edit image). Returns a task id, status, and output URLs.

ParametersJSON Schema
NameRequiredDescriptionDefault
waitNoPoll until the task reaches a terminal status.
modelNoRunAPI model slug for this model line.
promptNo
timeout_msNo
aspect_ratioNo
callback_urlNo
output_formatNo
poll_interval_msNo
source_image_urlsYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It states returns (task id, status, output URLs) but doesn't disclose whether the operation is synchronous or asynchronous, how waiting works, rate limits, permissions, or 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.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence, but it front-loads vendor-specific jargon ('Nano Banana task on RunAPI') instead of the functional purpose. It is efficient in length but poorly prioritized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 9 parameters, low schema coverage, and no annotations or output schema, the description is severely incomplete. It does not explain parameter usage, async behavior, or error handling, leaving an agent unable to invoke it reliably.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 22%, so the description must compensate. It does not mention any of the 9 parameters, failing to explain even the required source_image_urls or how wait, timeout_ms, and poll_interval_ms interact.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action (edit an image) but wraps it in vendor jargon ('Create a Nano Banana task on RunAPI') that obscures the actual purpose. It mentions returns but doesn't distinguish from sibling text_to_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus text_to_image or get_task. No mention of prerequisites or alternative tools is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_taskB

Fetch the current status and latest result payload for a nano-banana task.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesAsynchronous endpoint the task was created on.
task_idYesTask id returned when the task was created.

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It discloses that it returns the 'current status and latest result payload' but says nothing about authentication requirements (notable given a 'login' sibling), polling behavior, terminal task states, or error handling for invalid task ids.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence states the action, the resource, and what is returned, with no filler. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool with 100% schema coverage and no output schema, the description is minimally sufficient, but with no annotations it should do more to explain return semantics (e.g., pending vs. completed shapes) and auth expectations. The gaps are modest rather than severe.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: task_id and action are both documented in the schema, including the enum values for action. The description adds no syntax, format, or origin detail beyond what the schema already states, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetch') and resource ('current status and latest result payload for a nano-banana task'), which is precise enough for an agent to know what it retrieves. It does not explicitly differentiate itself from siblings like edit_image or text_to_image, though the 'task' framing implies post-creation polling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the reference to a 'task' and the schema's async-endpoint action enum suggest this is a polling tool used after creating a task. There is no explicit guidance on when to call it, how often, or what to do instead if the task does not exist yet.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

loginA

Authenticate RunAPI by opening a browser PKCE login flow and saving the API key to ~/.config/runapi/config.json.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNoRe-run browser login when the current credential comes from the local config file.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It discloses the interactive browser flow and the file write side effect (config.json). However, it does not mention that it may overwrite existing credentials or that it could block waiting for user input, though these are implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the action ('Authenticate RunAPI') and provides necessary details without extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple login tool with one optional parameter and no output schema, the description covers the core purpose and side effect. It lacks an explicit statement that this is a prerequisite for other tools, but that is implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the only parameter 'force' has a description). The tool description adds no additional meaning about parameters beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Authenticate'), target resource ('RunAPI'), method ('browser PKCE login flow'), and side effect (saving to config.json). It is distinct from sibling tools, none of which relate to authentication.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (to authenticate RunAPI) but does not explicitly say when to run it (e.g., before other RunAPI tools) or when to use the 'force' parameter. Since there are no alternative auth tools among siblings, 'vs alternatives' is not applicable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

text_to_imageC

Create a Nano Banana task on RunAPI (text to image). Returns a task id, status, and output URLs.

ParametersJSON Schema
NameRequiredDescriptionDefault
waitNoPoll until the task reaches a terminal status.
modelNoRunAPI model slug for this model line.
promptNo
timeout_msNo
aspect_ratioNo
callback_urlNo
output_formatNo
poll_interval_msNo
output_resolutionNo
reference_image_urlsNo

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden; it does add real value by disclosing the async task model and the return payload (task id, status, output URLs), which compensates for the absent output schema. However, it omits the default polling behavior of 'wait', timeout semantics, and cost/auth implications that the check_pricing and login siblings hint at.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the action and the return shape front-loaded, and no filler. It is efficient, though arguably too short given the tool's 10-parameter surface.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, zero-required, annotation-free asynchronous generation tool with no output schema, the description is far too thin. It explains the result payload but leaves the async lifecycle, model/quality options, and optional inputs such as reference_image_urls and callback_url entirely to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 20% across 10 parameters, so the description is expected to compensate, and it does not — prompt, model selection, aspect_ratio, reference_image_urls, callback_url, and output_format are all left unexplained. The only text offered concerns the return value, not the inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('Create') plus resource ('Nano Banana task') and the parenthetical '(text to image)' separates it from the sibling edit_image, which implies image-in/image-out. It is clear what the tool produces, though it never names edit_image as the contrasting alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to choose this over edit_image, nor any mention of the async workflow the schema implies (wait defaults to true, otherwise the sibling get_task must be polled). The agent must infer all usage conditions from the schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.12
    • Changedcheck_pricing1 field changed
      • changedInput schema / properties / model / enum
        Previous value: -[
-  "nano-banana-edit",
-  "nano-banana",
-  "nano-banana-2",
-  "nano-banana-pro"
-]New value: +[
+  "nano-banana-2-lite",
+  "nano-banana-edit",
+  "nano-banana",
+  "nano-banana-2",
+  "nano-banana-pro"
+]
    • Changededit_image14 fields changed
      • removedInput schema / additionalProperties
        Removed value: -false
      • addedInput schema / properties / aspect_ratio / anyOf
        Added value: +[
+  {
+    "const": "1:1",
+    "type": "string"
+  },
+  {
+    "const": "1:4",
+    "type": "string"
+  },
+  {
+    "const": "1:8",
+    "type": "string"
+  },
+  {
+    "const": "2:3",
+    "type": "string"
+  },
+  {
+    "const": "3:2",
+    "type": "string"
+  },
+  {
+    "const": "3:4",
+    "type": "string"
+  },
+  {
+    "const": "4:1",
+    "type": "string"
+  },
+  {
+    "const": "4:3",
+    "type": "string"
+  },
+  {
+    "const": "4:5",
+    "type": "string"
+  },
+  {
+    "const": "5:4",
+    "type": "string"
+  },
+  {
+    "const": "8:1",
+    "type": "string"
+  },
+  {
+    "const": "9:16",
+    "type": "string"
+  },
+  {
+    "const": "16:9",
+    "type": "string"
+  },
+  {
+    "const": "21:9",
+    "type": "string"
+  },
+  {
+    "const": "auto",
+    "type": "string"
+  }
+]
      • removedInput schema / properties / aspect_ratio / enum
        Removed value: -[
-  "1:1",
-  "9:16",
-  "16:9",
-  "3:4",
-  "4:3",
-  "3:2",
-  "2:3",
-  "5:4",
-  "4:5",
-  "21:9",
-  "auto"
-]
      • removedInput schema / properties / aspect_ratio / type
        Removed value: -"string"
      • addedInput schema / properties / callback_url
        Added value: +{
+  "type": "string"
+}
      • changedInput schema / properties / model / enum
        Previous value: -[
-  "nano-banana-edit"
-]New value: +[
+  "nano-banana-2-lite",
+  "nano-banana-edit"
+]
      • addedInput schema / properties / output_format / anyOf
        Added value: +[
+  {
+    "const": "png",
+    "type": "string"
+  },
+  {
+    "const": "jpeg",
+    "type": "string"
+  }
+]
      • removedInput schema / properties / output_format / enum
        Removed value: -[
-  "png",
-  "jpeg"
-]
      • removedInput schema / properties / output_format / type
        Removed value: -"string"
      • addedInput schema / properties / poll_interval_ms / maximum
        Added value: +9007199254740991
      • addedInput schema / properties / prompt
        Added value: +{
+  "maxLength": 20000,
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / source_image_urls
        Added value: +{
+  "items": {},
+  "type": "array"
+}
      • addedInput schema / properties / timeout_ms / maximum
        Added value: +9007199254740991
      • addedInput schema / required
        Added value: +[
+  "source_image_urls"
+]
    • Changedget_task1 field changed
      • changedInput schema / properties / action / description
        Previous value: -"Endpoint the task was created on."New value: +"Asynchronous endpoint the task was created on."
    • Addedlogin
    • Changedtext_to_image14 fields changed
      • removedInput schema / additionalProperties
        Removed value: -false
      • addedInput schema / properties / aspect_ratio / anyOf
        Added value: +[
+  {
+    "const": "1:1",
+    "type": "string"
+  },
+  {
+    "const": "9:16",
+    "type": "string"
+  },
+  {
+    "const": "16:9",
+    "type": "string"
+  },
+  {
+    "const": "3:4",
+    "type": "string"
+  },
+  {
+    "const": "4:3",
+    "type": "string"
+  },
+  {
+    "const": "3:2",
+    "type": "string"
+  },
+  {
+    "const": "2:3",
+    "type": "string"
+  },
+  {
+    "const": "5:4",
+    "type": "string"
+  },
+  {
+    "const": "4:5",
+    "type": "string"
+  },
+  {
+    "const": "21:9",
+    "type": "string"
+  },
+  {
+    "const": "auto",
+    "type": "string"
+  },
+  {
+    "const": "1:4",
+    "type": "string"
+  },
+  {
+    "const": "1:8",
+    "type": "string"
+  },
+  {
+    "const": "4:1",
+    "type": "string"
+  },
+  {
+    "const": "8:1",
+    "type": "string"
+  }
+]
      • removedInput schema / properties / aspect_ratio / enum
        Removed value: -[
-  "1:1",
-  "9:16",
-  "16:9",
-  "3:4",
-  "4:3",
-  "3:2",
-  "2:3",
-  "5:4",
-  "4:5",
-  "21:9",
-  "auto",
-  "1:4",
-  "1:8",
-  "4:1",
-  "8:1"
-]
      • removedInput schema / properties / aspect_ratio / type
        Removed value: -"string"
      • addedInput schema / properties / callback_url
        Added value: +{
+  "type": "string"
+}
      • changedInput schema / properties / model / enum
        Previous value: -[
-  "nano-banana",
-  "nano-banana-2",
-  "nano-banana-pro"
-]New value: +[
+  "nano-banana",
+  "nano-banana-2",
+  "nano-banana-2-lite",
+  "nano-banana-pro"
+]
      • addedInput schema / properties / output_format / anyOf
        Added value: +[
+  {
+    "const": "png",
+    "type": "string"
+  },
+  {
+    "const": "jpeg",
+    "type": "string"
+  },
+  {
+    "const": "jpg",
+    "type": "string"
+  }
+]
      • removedInput schema / properties / output_format / enum
        Removed value: -[
-  "png",
-  "jpeg",
-  "jpg"
-]
      • removedInput schema / properties / output_format / type
        Removed value: -"string"
      • removedInput schema / properties / output_resolution / enum
        Removed value: -[
-  "1k",
-  "2k",
-  "4k"
-]
      • addedInput schema / properties / poll_interval_ms / maximum
        Added value: +9007199254740991
      • addedInput schema / properties / prompt
        Added value: +{
+  "type": "string"
+}
      • addedInput schema / properties / reference_image_urls
        Added value: +{
+  "items": {},
+  "type": "array"
+}
      • addedInput schema / properties / timeout_ms / maximum
        Added value: +9007199254740991
  2. 4 tool updatesv0.1.0
    • First observedcheck_pricing
    • First observededit_image
    • First observedget_task
    • First observedtext_to_image
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 5 tools

Disambiguation4/5

edit_image and text_to_image are clearly distinct generation modes, and login/check_pricing are unambiguous. get_task is slightly generic given two creation paths, but its polling role is conceptually distinct from creation.

Naming Consistency4/5

Four tools follow a clean verb_noun pattern (get_task, edit_image, text_to_image, check_pricing). Only 'login' deviates as a bare verb, a minor inconsistency.

Tool Count5/5

Five tools is well-scoped for a model-API wrapper: two generation actions, one status poll, one auth, one pricing lookup. Each earns its place with no filler.

Completeness4/5

Covers create (both modes), poll, auth, and pricing, which handles the core generation lifecycle. Missing list/cancel-task operations are minor gaps an agent can work around.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers