Kokon

io.github.GabrieleLozuponePublished by GitHub account GabrieleLozuponev0.12.0Updated Nov 7, 2026

Generate and edit images offline with Qwen-Image 2.1 on your GPU. Needs the Kokon desktop app.

VerifiedSTDIODesktop onlyMedia & DesignAI & ML

Overview

AI-generated overview

Kokon lets an assistant generate and edit images offline with Qwen-Image 2.1 on the user's own GPU, through the Kokon desktop app.

What you can do
  • Generate images from text prompts, optionally with up to 10 reference images
  • Edit a single image by instruction, or edit image 1 using up to 9 other images
  • Inpaint a masked area and outpaint beyond the image borders
  • Upscale an image (default 2x, up to 8192 px)
  • Inspect image size, type and Kokon generation metadata, and check engine status, GPU, VRAM and job queue
When to use it
Useful when an assistant should produce or retouch images locally without cloud APIs, for example hero images for a README, background cleanup, product or person composites, or enlarging existing pictures.
Requirements
Local stdio process run with npx, needing Node.js 22 or newer (or the standalone executable shipped with the app). Requires the Kokon desktop app, opened once and set up so the model is downloaded: Windows with a 12 GB+ GPU or an Apple Silicon Mac with 16 GB+ (beta). No API key; the engine runs on 127.0.0.1 and starts on demand. Optional QLS_MCP_ALLOWED_DIRS lists extra readable/writable folders.
Before you install
File access is limited to the project folder, Kokon's output folder and folders in QLS_MCP_ALLOWED_DIRS, so widening that variable exposes more of the disk to the assistant. Tools write new image files, though existing files are never overwritten. The first call takes about a minute while the model loads, and images are not returned to the model unless include_preview is set.

Installation

In SourceWeft

  1. Open Kokon in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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:

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

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

json
{  "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.

Source: mcp/README.md at commit e411d96

Tools

8

generate_image

Generate image

Generate an image from a text prompt with the local Qwen-Image 2.1 model, optionally using reference images (a person, a product, a style) in a new scene. Write the full, detailed prompt yourself (see the prompt field): it is used as is. Dimensions are chosen automatically (aspect ratio can be inferred from the prompt, e.g. '16:9 hero image') unless width/height or aspect_ratio are given. Returns the absolute path of the saved PNG. Runs fully offline; typically 45 s–4 min.

Parametersseedwidthheightpromptrequiredqualityoutput_pathaspect_ratioinclude_previewreference_images

edit_image

Edit image

Edit an existing image with a natural-language instruction (e.g. 'make the background nighttime, keep the foreground unchanged'). Preserves the input's width, height and aspect ratio by default. The input file is never overwritten.

Parametersseedpromptrequiredqualityimage_pathrequiredoutput_pathinclude_previewpreserve_dimensions

edit_images

Edit with multiple references

Edit image 1 with the help of other images (up to 10 in all) and an instruction, e.g. put the product from image 2 in the hand of the person in image 1. Order matters: refer to them as image 1, image 2, ... in the prompt. The output follows image 1's aspect ratio unless width/height or aspect_ratio are given. For a new scene that only uses the images as references, use generate_image with reference_images.

Parametersseedwidthheightpromptrequiredqualityimage_pathsrequiredoutput_pathaspect_ratioinclude_preview

outpaint_image

Expand image (outpaint)

Extend an image beyond its borders. Give the expansion per side in pixels or percent; the canvas, mask and model-aligned sizes are built automatically and the original pixels are preserved exactly.

Parameterstopleftseedrightunitsbottompromptrequiredqualityimage_pathrequiredoutput_pathinclude_preview

inpaint_image

Inpaint image

Change only the masked area of an image (mask: white = change, black = keep): edit it, remove what is there, replace it, or add something inside it. The model is shown the area marked on a copy of the image; pixels outside the mask are preserved exactly.

Parametersseedactionpromptqualitymask_pathrequiredimage_pathrequiredoutput_pathinclude_preview

upscale_image

Upscale image

Enlarge an image (default 2x, or to a width/height up to 8192 px). Runs the upscaler model chosen in Kokon (Superscale-SP by default; seconds on a PC GPU, longer on a Mac; adds no new content). Saves a new file; the input is never overwritten.

Parametersscalewidthheightimage_pathrequiredoutput_pathinclude_preview

get_image_info

Image info

Width, height, aspect ratio, file type and, for images made by Kokon, the generation metadata (prompt, seed, model, steps...).

Parametersimage_pathrequired

get_generator_status

Generator status

Whether the local inference server is running and the model loaded, GPU and VRAM, the active job and the queue.

Takes no parameters.

Version history

8
  1. v0.12.0LatestNov 5, 2026
  2. v0.11.1Oct 29, 2026
  3. v0.11.0Oct 25, 2026
  4. v0.10.2Oct 23, 2026
  5. v0.10.1Oct 22, 2026
  6. v0.10.0Oct 20, 2026
  7. v0.9.4Oct 16, 2026
  8. v0.9.1Oct 12, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts