Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.
TypeScript ai-photo-editorcomfyui-alternativegenerative-fillimage-editingimage-generationinpaintinglinuxlocal-aimacosmcpmcp-servernano-banana-alternativeofflinephoto-editorprivacyqwen-imageqwen-image-2-1stable-diffusion-cppvulkanwindows
MCP: publishable npm package kokon-mcp + MCP Registry server.json
Gabriele Lozupone7b72c00caa7d
diff --git a/.gitignore b/.gitignoreindex b2a8eff..a1f9f04 100644--- a/.gitignore+++ b/.gitignore@@ -25,3 +25,4 @@ __pycache__//docs/launch-posts.md/docs/launch-day-prs.md/docs/engineering-writeup-outline.md+/mcp/LICENSEdiff --git a/README.md b/README.mdindex b2134a9..7e15686 100644--- a/README.md+++ b/README.md@@ -262,6 +262,13 @@ claude mcp add --scope user kokon -- "$env:LOCALAPPDATA\Kokon\kokon-mcp.exe"claude mcp add --scope user kokon -- /Applications/Kokon.app/Contents/MacOS/kokon-mcp```+Or, on either system with Node.js 22+, through [npm](https://www.npmjs.com/package/kokon-mcp)+(still needs the app installed):++```bash+claude mcp add --scope user kokon -- npx -y kokon-mcp+```+Then ask: *“Generate a hero image for this README and save it in docs/”* or *“Remove thebackground clutter from screenshot.png”*. The app doesn't need to be open, because the MCP serverstarts the engine on demand. The first call takes about a minute while the model loads.diff --git a/mcp/README.md b/mcp/README.mdnew file mode 100644index 0000000..f789d13--- /dev/null+++ b/mcp/README.md@@ -0,0 +1,66 @@+# kokon-mcp++MCP server for [Kokon](https://kokon.app). 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](https://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](https://github.com/GabrieleLozupone/kokon#use-it-from-your-ai-agent).++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++| Tool | What it does |+| --- | --- |+| `generate_image` | Text to image. Size chosen automatically, or set width/height or aspect ratio. |+| `edit_image` | Edit an image with an instruction. Keeps its size; never overwrites the input. |+| `edit_images` | Create an image from up to 10 reference images ("image 1", "image 2"...). |+| `inpaint_image` | Change only a masked area: edit, remove, replace or add something. |+| `outpaint_image` | Extend an image beyond its borders. |+| `upscale_image` | Enlarge an image (default 2x, up to 8192 px). |+| `get_image_info` | Size, type and, for Kokon images, the prompt, seed and settings. |+| `get_generator_status` | Engine 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](https://github.com/GabrieleLozupone/kokon/tree/master/mcp).diff --git a/mcp/package.json b/mcp/package.jsonindex 4cc3efe..2d3f82a 100644--- a/mcp/package.json+++ b/mcp/package.json@@ -1,25 +1,45 @@{"name": "kokon-mcp","version": "0.9.1",+ "mcpName": "io.github.GabrieleLozupone/kokon","license": "AGPL-3.0-only",- "private": true,- "description": "MCP server for Kokon (local image generation and editing)",+ "description": "MCP server for Kokon: generate and edit images offline with Qwen-Image 2.1 on your own GPU. Requires the Kokon desktop app (Windows/macOS).",+ "keywords": ["mcp", "mcp-server", "model-context-protocol", "image-generation", "image-editing", "qwen-image", "local", "offline", "kokon"],+ "author": "Gabriele Lozupone",+ "homepage": "https://kokon.app",+ "bugs": "https://github.com/GabrieleLozupone/kokon/issues",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/GabrieleLozupone/kokon.git",+ "directory": "mcp"+ },"type": "module",+ "bin": {+ "kokon-mcp": "build/kokon-mcp.cjs"+ },+ "files": [+ "build/kokon-mcp.cjs",+ "README.md",+ "LICENSE"+ ],+ "engines": {+ "node": ">=22"+ },"scripts": {- "build": "esbuild src/index.ts --bundle --platform=node --target=node22 --format=cjs --outfile=build/kokon-mcp.cjs",+ "build": "esbuild src/index.ts --bundle --platform=node --target=node22 --format=cjs --banner:js=\"#!/usr/bin/env node\" --outfile=build/kokon-mcp.cjs","test": "vitest run","typecheck": "tsc --noEmit",- "build:exe": "node scripts/build-exe.mjs"- },- "dependencies": {- "@modelcontextprotocol/sdk": "^1.32.1",- "zod": "^4.6.5"+ "build:exe": "node scripts/build-exe.mjs",+ "prepack": "node -e \"require('fs').copyFileSync('../LICENSE','LICENSE')\"",+ "prepublishOnly": "npm run build && npm test"},"devDependencies": {+ "@modelcontextprotocol/sdk": "^1.32.1","@types/node": "^26.6.4","esbuild": "^0.28.2","postject": "^1.0.0-alpha.6","typescript": "^7.0.2",- "vitest": "^5.0.3"+ "vitest": "^5.0.3",+ "zod": "^4.6.5"}}diff --git a/mcp/server.json b/mcp/server.jsonnew file mode 100644index 0000000..4ac78be--- /dev/null+++ b/mcp/server.json@@ -0,0 +1,39 @@+{+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",+ "name": "io.github.GabrieleLozupone/kokon",+ "title": "Kokon",+ "description": "Generate and edit images offline with Qwen-Image 2.1 on your GPU. Needs the Kokon desktop app.",+ "version": "0.9.1",+ "websiteUrl": "https://kokon.app",+ "repository": {+ "url": "https://github.com/GabrieleLozupone/kokon",+ "source": "github",+ "subfolder": "mcp"+ },+ "icons": [+ {+ "src": "https://raw.githubusercontent.com/GabrieleLozupone/kokon/master/assets/brand/icon/kokon-icon-256.png",+ "mimeType": "image/png",+ "sizes": ["256x256"]+ }+ ],+ "packages": [+ {+ "registryType": "npm",+ "registryBaseUrl": "https://registry.npmjs.org",+ "identifier": "kokon-mcp",+ "version": "0.9.1",+ "runtimeHint": "npx",+ "transport": { "type": "stdio" },+ "environmentVariables": [+ {+ "name": "QLS_MCP_ALLOWED_DIRS",+ "description": "Extra folders the server may read and write, separated by semicolons. The project folder and Kokon's output folder are always allowed.",+ "isRequired": false,+ "isSecret": false,+ "format": "string"+ }+ ]+ }+ ]+}diff --git a/mcp/src/service.ts b/mcp/src/service.tsindex 033ae79..682e0d3 100644--- a/mcp/src/service.ts+++ b/mcp/src/service.ts@@ -100,9 +100,9 @@ export class ServiceClient {const exe = findServiceExe();if (!exe) {throw new ServiceError(- `Kokon is not installed (${SERVICE_EXE} not found).`,+ `Kokon is not installed (${SERVICE_EXE} not found). This MCP server needs the Kokon desktop app (Windows or macOS).`,"not_installed",- `Install Kokon, or set QLS_SERVICE_EXE to the path of ${SERVICE_EXE}.`,+ `Download Kokon from https://kokon.app, open it once and finish the setup, then try again. If it is installed in an unusual place, set QLS_SERVICE_EXE to the path of ${SERVICE_EXE}.`,);}// Detached: the service outlives this MCP process and exits on its own when idle.diff --git a/mcp/src/tools.ts b/mcp/src/tools.tsindex 1d36e71..2aef1da 100644--- a/mcp/src/tools.ts+++ b/mcp/src/tools.ts@@ -394,7 +394,13 @@ export const handlers = {export function toErrorResult(e: unknown): ToolResult {if (e instanceof PathError) return errorResult(e.message, "invalid_path");- if (e instanceof ServiceError) return errorResult(e.message, e.code, e.suggestion, e.detail);+ if (e instanceof ServiceError) {+ const suggestion =+ e.code === "missing_model"+ ? "Open the Kokon app and finish the setup (it downloads the model), or use Settings → Models → Set up models…, then try again."+ : e.suggestion;+ return errorResult(e.message, e.code, suggestion, e.detail);+ }if (e instanceof z.ZodError) return errorResult(e.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "), "invalid_input");return errorResult(e instanceof Error ? e.message : String(e), "internal");}