Skip to main content
Glama
RunPod Image MCP Server

RunPod Image MCP Server

RunPod Image MCP Server

An MCP server that gives Claude Code and Cursor the ability to generate and edit images using RunPod's Seedream V4 and Nano Banana Pro APIs.

Prerequisites

Related MCP server: nb-mcp

Setup

Claude Code

Quick Start (one command):

claude mcp add runpod-image-apis \
  -e RUNPOD_API_KEY=your_api_key \
  -- uvx runpod-mcp-server

Restart Claude Code and the tools are available.

Manual setup (clone and run locally): add to .mcp.json (project-level or ~/.claude/.mcp.json for global):

{
  "mcpServers": {
    "runpod-image-apis": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/runpod-image-mcp", "runpod-mcp-server"],
      "env": {
        "RUNPOD_API_KEY": "your_api_key"
      }
    }
  }
}

Replace /path/to/runpod-image-mcp with the absolute path to the cloned repo.

Cursor

Quick Start: create or edit your MCP config and add the server.

  • Project-only: create .cursor/mcp.json in your project root.

  • All projects: create ~/.cursor/mcp.json in your home directory.

If using uvx (no clone needed):

{
  "mcpServers": {
    "runpod-image-apis": {
      "command": "uvx",
      "args": ["runpod-mcp-server"],
      "env": {
        "RUNPOD_API_KEY": "your_api_key"
      }
    }
  }
}

If running from a cloned repo:

git clone https://github.com/jashwanth0712/runpod-image-mcp.git
cd runpod-image-mcp

Then use one of the configs below.

In project .cursor/mcp.json (use ${workspaceFolder} so it works for any project that contains the clone):

{
  "mcpServers": {
    "runpod-image-apis": {
      "command": "uv",
      "args": ["run", "--directory", "${workspaceFolder}", "runpod-mcp-server"],
      "env": {
        "RUNPOD_API_KEY": "your_api_key"
      }
    }
  }
}

In global ~/.cursor/mcp.json, use the absolute path to the repo:

{
  "mcpServers": {
    "runpod-image-apis": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/runpod-image-mcp", "runpod-mcp-server"],
      "env": {
        "RUNPOD_API_KEY": "your_api_key"
      }
    }
  }
}

Replace /path/to/runpod-image-mcp with the actual path. Restart Cursor (or reload the window) so the new MCP server is picked up.

Available Tools

Tool

Description

generate_image

Generate images from text prompts (Seedream V4 T2I). Supports sizes up to 4096x4096, negative prompts, and seed control.

edit_image

Edit/transform existing images (Nano Banana Pro Edit). Accepts 1-10 image URLs with 1k/2k/4k resolution options.

check_job_status

Check the status of a previously submitted generation or editing job.

get_api_info

Get reference info about supported parameters, sizes, pricing, and capabilities.

Usage Examples

Once configured, ask Claude or Cursor naturally:

Generate a photorealistic sunset over snow-capped mountains with dramatic clouds
Edit this product photo to have a white background and studio lighting: https://example.com/photo.jpg
Check the status of job abc123-def456 from Seedream
What sizes does the Seedream API support?

Troubleshooting

  • Server won't start -- Verify your RUNPOD_API_KEY is correct.

  • Job timeouts -- Increase max_wait_seconds or use check_job_status to poll manually. Large images take longer.

  • No image URL in response -- Check the RunPod console for job details and endpoint health.

License

MIT

Available Tools

4 tools
check_job_statusA

Check the status of a previously submitted job.

Use this tool to monitor long-running jobs or check on jobs that timed out. Works for both image generation (Seedream) and image editing (Nano Banana) jobs.

Args: job_id: Job ID returned from generate_image or edit_image. Format: typically a UUID like "abc123-def456" endpoint_type: Which API the job was submitted to: - "seedream": For text-to-image generation jobs - "nano_banana": For image editing jobs

Returns: Current job status with result URL if completed. Possible statuses: IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED

Examples: - Check a generation job: check_job_status("abc123-def456", "seedream") - Check an editing job: check_job_status("xyz789-ghi012", "nano_banana")

Inputs: job_id (required), endpoint_type (required). Returns: result

edit_imageA

Edit or transform images using Nano Banana Pro Edit API.

This tool applies AI-powered edits to existing images based on text descriptions.
You can adjust style, add/remove elements, change backgrounds, enhance quality, etc.

Args:
    prompt: Description of desired edits or transformations. Be specific about
        what changes you want (e.g., "change background to sunset", "add studio
        lighting", "remove watermark", "enhance colors").
    image_urls: List of 1-10 publicly accessible image URLs to edit.
        Images must be reachable via HTTP/HTTPS. Common formats supported: JPEG, PNG, WebP.
    resolution: Output resolution. Options:
        - "1k": Lower resolution, faster processing ($0.14)
        - "2k": Standard resolution, best value ($0.14) [default]
        - "4k": High resolution for detailed work ($0.24)
    aspect_ratio: Output aspect ratio (optional). If not specified, maintains original.
        Options: "1:1" (square), "16:9" (landscape), "9:16" (portrait), "3:2", "2:3",
        "4:3", "3:4", "4:5", "5:4", "21:9"
    output_format: Output file format. Options:
        - "jpeg": Smaller file size, good for photos (default)
        - "png": Lossless quality, good for graphics
    enable_base64_output: Return base64-encoded image data instead of URL.
        Default: false (return URL)
    enable_sync_mode: Enable synchronous mode for immediate processing.
        Default: false (asynchronous processing)
    max_wait_seconds: Maximum time to wait for job completion in seconds.
        Default: 300 (5 minutes)

Returns:
    Success message with edited image URL, resolution, cost, and job ID.
    Format: "✓ Image edited successfully!

URL: ... Resolution: ... Cost: $... Job ID: ..."

Examples:
    - "Add dramatic sunset lighting to this portrait"
    - "Remove background and replace with solid white"
    - "Enhance colors and increase sharpness for product photography"
    - "Transform into oil painting style while keeping the subject"

Inputs: prompt (required), image_urls (required), resolution, aspect_ratio, +4 more. Returns: result

generate_imageA

Generate images from text descriptions using Seedream V4 T2I.

This tool creates high-quality photorealistic or artistic images from text prompts.
Jobs are processed asynchronously and typically complete in 30-90 seconds.

Args:
    prompt: Detailed text description of the desired image. Be specific about
        style, composition, lighting, colors, and subject matter.
    negative_prompt: Elements to exclude from the image (e.g., "blurry, low quality,
        distorted faces"). Optional but recommended for better results.
    size: Image dimensions in format "width*height" (e.g., "2048*2048").
        Valid range: 1024-4096 pixels for both width and height.
        Default: "2048*2048"
    seed: Random seed for reproducibility. Use -1 for random generation (default),
        or provide a specific number to reproduce results.
    enable_safety_checker: Enable content safety filtering. Default: true.
        Set to false only if you need to bypass content filtering.
    max_wait_seconds: Maximum time to wait for job completion in seconds.
        Default: 300 (5 minutes). Increase for very large images.

Returns:
    Success message with image URL, generation details, and job ID for status tracking.
    Format: "✓ Image generated successfully!

URL: ... Size: ... Seed: ... Job ID: ..."

Examples:
    - "A photorealistic sunset over snow-capped mountains with dramatic clouds"
    - "An oil painting of a medieval castle on a cliff, fantasy art style"
    - "Product photo of a sleek smartphone on a white background, studio lighting"

Inputs: prompt (required), negative_prompt, size, seed, +2 more. Returns: result

get_api_infoA

Get information about supported parameters and capabilities.

This tool provides reference information about what each API supports, including valid parameter values, pricing, and best practices.

Args: api: Which API to get information about: - "seedream": Seedream V4 T2I text-to-image generation - "nano_banana": Nano Banana Pro Edit image editing - "all": Information about both APIs (default)

Returns: Formatted reference information including supported parameters, constraints, pricing, and usage recommendations.

Examples: - Get all API info: get_api_info() - Get only Seedream info: get_api_info("seedream") - Get only Nano Banana info: get_api_info("nano_banana")

Inputs: api. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: generating images, editing images, checking job status, and getting API info. No overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with underscores (check_job_status, edit_image, generate_image, get_api_info), making them predictable and easy to understand.

    Tool Count5/5

    With 4 tools, the server is well-scoped for its purpose—image generation and editing—without being too sparse or overwhelming.

    Completeness4/5

    The tool set covers the core workflows (generate, edit, check status, get info) but lacks features like job cancellation or listing, which are minor gaps.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers