NIMGEN

Why NIMGEN?

NIMGEN is the first MCP server specifically built for NVIDIA NIM FLUX models.

Most image generation MCP servers require separate API keys from providers like Replicate, Stability AI, or OpenAI. NIMGEN uses your existing NVIDIA API key — the same one you already use for LLM inference via NIM.

Related MCP server: Flux Schnell Server

Quick Start

1. Get your NVIDIA API Key

If you don't have one already:

1. Go to build.nvidia.com

2. Sign in or create a free account

3. Navigate to API Keys section

4. Click Generate Key

5. Copy your key (starts with nvapi-...)

Free tier includes 1,000+ credits for testing!

2. Set the environment variable

# Windows (PowerShell)
$env:NVIDIA_API_KEY = "nvapi-your-key-here"

# Linux / macOS
export NVIDIA_API_KEY="nvapi-your-key-here"

# Verify it's set (optional)
echo $env:NVIDIA_API_KEY  # Windows
echo $NVIDIA_API_KEY      # Linux/macOS

3. Add to your MCP client

OpenCode / Oh-My-OpenCode

Add to your opencode.jsonc:

{
  "mcp": {
    "nimgen": {
      "type": "local",
      "command": ["npx", "-y", "nimgen"],
      "environment": {
        "NVIDIA_API_KEY": "{env:NVIDIA_API_KEY}"
      },
      "enabled": true,
      "timeout": 60000
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "nimgen": {
      "command": "npx",
      "args": ["-y", "nimgen"],
      "env": {
        "NVIDIA_API_KEY": "nvapi-your-key-here"
      }
    }
  }
}

Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "servers": {
    "nimgen": {
      "command": "npx",
      "args": ["-y", "nimgen"],
      "env": {
        "NVIDIA_API_KEY": "nvapi-your-key-here"
      }
    }
  }
}

Glossary

New to AI image generation or MCP? Here's what the terms mean:

Tools

generate_image

Generate an image from a text description using NVIDIA NIM FLUX models.

edit_image

Edit an existing image using text instructions (FLUX.1-Kontext).

Note: image_path must be within the output directory or current working directory for security.

list_models

List all available FLUX models on NVIDIA NIM and their capabilities.

Models

Configuration

All configuration is via environment variables:

Self-Hosted NIM

If you're running NIM locally with Docker, set the base URL:

export NIMGEN_BASE_URL="http://localhost:8000/v1"

Limitations

Rate Limits

NVIDIA NIM has rate limits based on your account tier:

• Free tier: ~1,000 credits (varies)

• Paid tier: Higher limits

When you hit rate limits, you'll see: "Rate limit exceeded. Please wait a moment and try again."

Examples

Social Media Post

Generate an image: Professional tech company social media banner
with gradient background from dark blue to purple, abstract
geometric shapes, and clean modern aesthetic.

Product Mockup

Edit this image: Add a holographic logo floating above
the laptop screen with volumetric lighting and lens flare.

Tattoo Preview

Edit this image: Add a realistic Japanese dragon tattoo
covering the forearm, black and gray style with fine
line work, photorealistic skin texture.

Website Hero Image

Generate an image: Futuristic data center with rows of
glowing server racks, blue and green LED lighting,
cinematic perspective.

FAQ

General

Q: What is NIMGEN? A: NIMGEN is an MCP (Model Context Protocol) server that lets you generate and edit images using NVIDIA's FLUX.1 models through your existing NVIDIA API key.

Q: Do I need a separate subscription? A: No! NIMGEN uses your existing NVIDIA NIM API key. If you already use NVIDIA for LLM inference, you're all set.

Q: Is it free? A: NVIDIA offers free credits (1,000+) when you sign up. After that, you pay per image generated through NVIDIA's pricing.

Q: Which model should I use? A: Use flux-1-dev for high-quality final images, flux-1-schnell for quick prototypes, and flux-1-kontext for editing existing images.

Troubleshooting

Q: I get "NVIDIA_API_KEY environment variable is required" A: Make sure you've set the environment variable:

• Windows: $env:NVIDIA_API_KEY = "nvapi-your-key"

• Linux/macOS: export NVIDIA_API_KEY="nvapi-your-key"

Q: I get "Invalid NVIDIA API key" A: Your key might be incorrect or expired. Get a new key at build.nvidia.com. Make sure it starts with nvapi-.

Q: I get "Rate limit exceeded" A: You've hit NVIDIA's API limits. Wait a few seconds and try again. Consider upgrading your NVIDIA account for higher limits.

Q: I get "Access denied: path outside allowed directories" A: For security, edit_image only accepts images from the output directory or current working directory. Move your image there first.

Q: I get "Invalid image format" A: NIMGEN supports PNG, JPEG, WebP, and GIF. Make sure your image is in one of these formats.

Q: I get "Image too large" A: Maximum image size is 50MB. Compress your image or use a smaller file.

Q: I get "Prompt too long" A: Maximum prompt length is 2,000 characters. Shorten your prompt.

Q: Generation is slow A: FLUX.1 Dev takes 20-50 steps and can take 30-60 seconds. Use flux-1-schnell for faster generation (4 steps, ~5-10 seconds).

Q: I get "NVIDIA NIM service temporarily unavailable" A: NVIDIA's servers are experiencing issues. Wait a few minutes and try again.

Technical

Q: What Node.js version do I need? A: Node.js 18.0.0 or higher is required.

Q: Can I use NIMGEN with self-hosted NIM? A: Yes! Set NIMGEN_BASE_URL to your local NIM endpoint:

export NIMGEN_BASE_URL="http://localhost:8000/v1"

Q: Where are images saved? A: By default, images are saved to ./nimgen-output/. Change with NIMGEN_OUTPUT_DIR.

Q: Can I generate multiple images at once? A: Currently, NIMGEN generates one image per call. Batch generation is on the roadmap.

Troubleshooting

Common Errors

Debug Mode

To see more details about what's happening:

# Run directly to see startup logs
NVIDIA_API_KEY=nvapi-... npx nimgen

Development

# Clone and install
git clone https://github.com/gabriel-ferraresi/NIMGEN.git
cd NIMGEN
npm install

# Build
npm run build

# Run locally
NVIDIA_API_KEY=nvapi-... node dist/index.js

License

Apache-2.0 — see LICENSE for details.