Skip to content

armgit / kokon

Public Imported from GitHub
0

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.

MCP: publishable npm package kokon-mcp + MCP Registry server.json

Gabriele Lozupone7b72c00caa7d
diff --git a/.gitignore b/.gitignore
index 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/LICENSE
diff --git a/README.md b/README.md
index 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 the
background clutter from screenshot.png”*. The app doesn't need to be open, because the MCP server
starts the engine on demand. The first call takes about a minute while the model loads.
diff --git a/mcp/README.md b/mcp/README.md
new file mode 100644
index 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.json
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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");
}