mcpField
K
Kokon

Kokon

Local
kokon.appMedia & Design230Updated today
RepositoryVisit website

About Kokon

Kokon is an MCP server that lets AI coding tools generate and edit images with Qwen-Image 2.1 on a local GPU. It requires the Kokon desktop app and keeps processing on the device.

Key features

  1. 01Offline image generation
  2. 02Image editing with reference images
  3. 03Inpainting and outpainting
  4. 04Image upscaling and metadata
  5. 05Project-folder file access limits

Use cases

  1. 01Creating project and README artwork
  2. 02Editing screenshots with instructions
  3. 03Changing or extending selected image areas

MCP support

Exposes image generation, editing, inspection, and engine-status tools to MCP clients. The server bridges clients to the Kokon desktop app and local GPU engine.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "gabrielelozupone-kokon": {
      "command": "npx",
      "args": [
        "-y",
        "kokon-mcp"
      ],
      "env": {
        "QLS_MCP_ALLOWED_DIRS": "<QLS_MCP_ALLOWED_DIRS>"
      }
    }
  }
}
Run commandnpx -y kokon-mcp
Environment variables to set
QLS_MCP_ALLOWED_DIRSExtra folders the server may read and write, separated by semicolons. The project folder and Kokon's output folder are always allowed.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmkokon-mcp0.11.1

Tools

8

Saved tool list · updated 2d ago

ParameterTypeRequiredDescription
seedintegerNoSeed for reproducible results; omit or -1 for random
widthintegerNoOutput width in pixels (needs height too). Omit to choose automatically.
heightintegerNoOutput height in pixels (needs width too).
promptstringYesWhat to generate, in natural language
qualityenumNoAll run Qwen-Image 2.1 Turbo (8 steps): fast = ~1 MP (the default, fastest); balanced = ~1.5K; quality = native 2K (slowest; edits share 2K with their references)fast | balanced | quality
output_pathstringNoOptional destination (absolute, or relative to the project). Must be inside the project or the app output folder. Existing files are never overwritten; a numbered name is used instead.
aspect_ratiostringNoAspect ratio such as 1:1, 4:3, 3:4, 16:9, 9:16, or auto (inferred from the prompt)
include_previewbooleanNoAlso return a small JPEG preview in the tool result. Default false: images stay local and are not sent to the model.

Details

From the project README

kokon-mcp

MCP server for Kokon. It lets Claude Code, Cursor, Claude Desktop and other MCP clients generate and edit images with Qwen-Image 2.1, running offline on your own GPU. No API key, no cloud. Everything stays on 127.0.0.1.

Requires the Kokon desktop app (Windows with a 12 GB+ GPU: NVIDIA, or AMD/Intel in beta; or an Apple Silicon Mac, beta, 16 GB+). Download it from kokon.app, open it once and finish the setup so the model is downloaded. This package is only the bridge between your AI agent and the app. The app doesn't need to be open: the server starts the engine on demand.

Setup

Claude Code:

claude mcp add --scope user kokon -- npx -y kokon-mcp

Any client that takes the standard JSON config (.mcp.json, Claude Desktop, Cursor...):

{
  "mcpServers": {
    "kokon": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kokon-mcp"]
    }
  }
}

Needs Node.js 22 or newer. The Kokon installer also ships the same server as a standalone executable (kokon-mcp.exe / kokon-mcp inside the app), if you prefer not to use Node. See the main README.

Then ask: "Generate a hero image for this README and save it in docs/" or "Remove the background clutter from screenshot.png". The first call takes about a minute while the model loads.

Tools

Prompts are used exactly as your assistant writes them: Kokon's own prompt writer (Prompt+) does not run for MCP, so the assistant writes the full description. The tool descriptions tell it how.

ToolWhat it does
generate_imageText to image, optionally with up to 10 reference images (a person, a product, a style) in a new scene. Size chosen automatically, or set width/height or aspect ratio.
edit_imageEdit an image with an instruction. Keeps its size; never overwrites the input.
edit_imagesEdit image 1 with the help of up to 9 more images ("image 1", "image 2"...).
inpaint_imageChange only a masked area: edit, remove, replace or add something.
outpaint_imageExtend an image beyond its borders.
upscale_imageEnlarge an image (default 2x, up to 8192 px).
get_image_infoSize, type and, for Kokon images, the prompt, seed and settings.
get_generator_statusEngine state, GPU, VRAM and job queue.

Behavior and safety

  • Every result returns the absolute path of the saved file, its size, seed and metadata.
  • Reads and writes are limited to the project folder (CLAUDE_PROJECT_DIR or the working directory), Kokon's output folder and folders listed in QLS_MCP_ALLOWED_DIRS (separated by semicolons). Existing files are never overwritten.
  • Images are not sent back to the model by default. Pass include_preview: true for a small JPEG.
  • Progress is reported through MCP progress notifications.

License

AGPL-3.0-only. The Qwen-Image 2.1 model weights the app downloads are under the Qwen Research License (non-commercial). Source: github.com/GabrieleLozupone/kokon.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.