nai-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
nai-mcp — NovelAI Image Generation MCP Server
English | 简体中文
A standalone stdio MCP Server that plugs into any MCP-capable agent — Claude Code, Codex, Cline, and friends. Request formats follow the official OpenAPI docs (image.novelai.net/docs). Image generation always goes through a named workflow: set_* tools only fill in parameters at zero cost; generation happens only after explicit confirmation.
Design philosophy: why named workflows
Pointing an agent straight at an image-generation API brings three built-in risks: accidentally triggering a billed generation, burning money on parameter trial-and-error, and getting dragged off-task by the images it looks at. Every design decision in this tool addresses one of these:
1. Generation = two phases: free parameter writes → the sole billing gate
Generating is deliberately split in two. The set_prompt / set_gen_param / set_characters / set_image / set_mask / set_precise_reference family are write-only tools: they touch no API and consume no Anlas, and they are all partial updates (calls compose in any order; rewriting the same field is idempotent). Only three executor tools — generate_image / enhance_image / upscale_image — ever spend money. They are the single gate: probing parameters costs nothing, no matter how many tries.
2. Workflows are named JSON files, not server memory
Each workflow is a readable file workflows/<name>.json: diffable, hand-editable, and survives across sessions. After an agent restarts and forgets, read_workflow reconstructs the complete previous state; parallel creative lines live in separate named workflows (e.g. protagonist / sketch_runs).
3. Estimate first, generate only after confirmation
read_workflow / estimate_anlas are always free: they return the fully resolved parameters plus an Anlas estimate (with Opus free-tier judgment, live V5 quota pool usage, and the precise-reference surcharge). The agreed order of operations is set → estimate → (user confirms) → generate, and the server's instructions field encodes that protocol directly into agent tool guidance.
4. Default everything to 0 Anlas
Hard rules baked into the server instructions: default model nai-diffusion-5-full; the default parameter combination aligns with the Opus free tier (first image free at steps ≤ 28 and ≤ 1024×1024); n_samples defaults to 1; and no cost-producing parameter or tool is chosen without the user's explicit request. Every estimate also says "subject to server-side billing".
5. The agent never needs image-editing skills
The biggest friction of inpainting is that agents can't paint masks. set_mask accepts rects — a list of 0–1-normalized rectangles — and the server renders the mask itself, then runs the full official frontend pipeline: 8px-latent-grid quantization → hard-edged mask in the request → feathered soft mask → compositing the result back onto the source image. The agent only needs to say "repaint the top-left region spanning 40% of the width", with zero image-editing capability.
6. Normalize prompts before generating
The workflow protocol says: pass every prompt through search_tag first — Chinese / aliases / semantic queries → proper Danbooru-style tags (looking at viewer, not prose). Output quality is decided by the tag vocabulary, not by the agent's vocabulary.
7. Everything follows official docs and the reference client — nothing invented
The Anlas formula, sampling presets, UC preset texts, inpainting model mapping, the precise-reference black-canvas spec (original sizes cause HTTP 500), and the V5 quota-pool semantics all mirror the official OpenAPI and the public behavior of the reference client Aaalice_NAI_Launcher, with source attributions in code comments. When the upstream caliber changes, exactly one module changes too — the server stays self-consistent.
Related MCP server: NovelAI Image MCP
Quick start
cd nai_mcp
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt
# Optional: build the tag database (auto-downloads the Launcher's published tag_catalog.db)
.venv/Scripts/python tool/build_tag_vector_db.py --db tag_vectors.db --with-ffdkjRegister a stdio server in your MCP client, token via env:
{
"mcpServers": {
"nai-mcp": {
"command": "C:/Users/your-name/codes/nai_mcp/.venv/Scripts/python.exe",
"args": ["C:/Users/your-name/codes/nai_mcp/server.py"],
"env": { "NAI_TOKEN": "pst-your-persistent-token" }
}
}
}NAI_TOKEN: a NovelAI persistent token (starts with pst-; account settings → API tokens → create), or a short-lived user access token.
Global agent conventions (written into the server
instructions): default model is nai-diffusion-5-full; aim for 0 Anlas by default (Opus free tier: steps ≤ 28, ≤ 1024×1024); normalize prompts viasearch_tagbefore writing; prefercategory=charactertags for characters/subjects.
Tool overview
Tool | Purpose | Anlas |
| List all workflow names | No |
| Create an empty workflow; | No |
| Delete one workflow (permanent). Only call when the user explicitly names it | No |
| Delete every workflow (permanent). Only call when the user explicitly asks to clear all | No |
| Clear all PNGs in the output directory (default | No |
| Write the positive prompt ( | No |
| Write generation parameters (model/size/steps/guidance/sampler/seed/samples/UC preset/cfg_rescale/noise schedule/use_coords), partial update | No |
| V4+ multi-character prompts; per-character | No |
| img2img source image (local PNG); | No |
| inpaint mask: rectangles | No |
| Precise reference / Character Reference: a reference PNG locking a character's look or a style; multiple calls append; | No |
| Read a workflow + Anlas estimate, for confirmation | No |
| Estimate-only, no generation; V5 workflows additionally show live Opus quota usage | No |
| All legal values plus per-model defaults/constraints | No |
| Generate per the workflow: source image → img2img; characters set → V4 multi-character structure | Yes |
| Enhance (full repaint + upscale); level 1–5, default 3; factor 2.0/1.5/1.0 auto-falls-back under the pixel cap | Yes |
| Cloud upscaling via | ≤4 (free ≤640×640 on Opus) |
| Danbooru tag search (Chinese/aliases/literal; | No |
Workflows are stored as nai_mcp/workflows/<name>.json (directory overridable via env NAI_MCP_WORKFLOW_DIR). set_* tools only do partial updates; compose them in any order, then generate.
Dangerous tools (workflow deletion, image clearing) hard-code "only call when the user explicitly asks" in their descriptions, leaving irreversible actions to the user.
Models & sampling presets
Supported models (default in bold): nai-diffusion-5-full, nai-diffusion-5-curated, nai-diffusion-5-full-medium, nai-diffusion-4-5-full, nai-diffusion-4-5-curated, nai-diffusion-4-full, nai-diffusion-3
Presets (from Launcher
ModelCapabilities): 28 steps (V5 Medium fixed at 14); guidance V5 4.0 / V4.5 5.0 / V4 5.5 / V3 5.0; samplerk_euler_ancestral; noise schedule karras; UC preset heavy; img2img strength 0.7 / noise 0.0V5 specifics: UC
lightuses V5-exclusive copy;nai-diffusion-5-full-mediumdoes not sendcfg_rescale; Anlas model multiplier 1.5, and the Opus free tier becomes an official quota pool (see the Billing section; estimate text notes it automatically)Official quality tags and UC preset text are completed automatically; DDIM is V3-only (V4+ falls back to Euler Ancestral per the official rules)
Precise reference (sent as
director_reference*fields): V4.5 Curated / V4.5 Full only (matching LaunchersupportsPreciseReference); typescharacter/style/character&style(default);strengthdefaults to 1.0 (passed through as strength),fidelitydefaults to 1.0 (sent as1.0 - fidelitysecondary strength);normalize_reference_strength_multiple=truealways. Reference images are auto-normalized per the official spec at request time: pick the closest-aspect target among1024×1536/1536×1024/1472×1472, scale to fit (bilinear), and center on a black canvas — raw-size images get HTTP 500 (matching LauncherensurePngFormat; interpolation differs)UC convention: presets (heavy/light/humanFocus/none) already carry the full official quality negative list (lowres, worst quality, …). A custom
ucshould list only the specific defects/composition issues to avoid — repeating quality words would amplify their relative weight
Inpaint (partial repaint)
When a workflow has both a source image and a mask, generate_image follows the official infill rules automatically:
The model switches to the inpainting variant (e.g.
nai-diffusion-4-5-full→…-inpainting; V5 Curated maps officially to V4.5 Curated Inpainting); the request carries themaskfield andextra_noise_seed = seed - 1Two mask sources:
rects(the server renders the normalized rectangles — the agent needs no image-editing skills) ormask_path(a PNG where white = repaint; auto-binarized and resized)Mask
strengthdefaults to 1.0 (LauncherinpaintStrength); below 1.0 the request attaches animg2imgblock reusing the original latent per official rules. Source-imagestrength(default 0.7) controls overall change; the two are independentEnhance and masks are mutually exclusive (enhance repaints the whole image); calling with a mask set errors out explicitly
The mask pipeline mirrors the official frontend: binarize → latent 8px quantization (the request mask has hard edges) → feathered soft mask, only used for compositing results back afterwards
Billing & Anlas estimation
Ported from the Launcher AnlasCalculator (modern-model formula). Estimation tools query the subscription tier automatically (GET /user/subscription); every estimate notes "subject to server-side billing":
Generation: first image free on Opus at steps ≤ 28 and ≤ 1024×1024
Cloud upscaling: free ≤640×640 input on Opus, otherwise 1–4 Anlas by input-area tiers
When the subscription query fails, estimating assumes non-Opus and says so
Precise references: +5 Anlas per reference per sample (not covered by the Opus free tier)
V5 quota usage (read_workflow / estimate_anlas)
On V5 the Opus free tier is a quota pool, not unconditional freeness: it refills over time and is tied to image area (official caliber: 1% ≈ 17.3 free ≤1MP images; larger images count as 2/3/4 units each), and an overdrawn pool bills V5 generations at normal Anlas prices. Estimate text appends a live usage line (matching Launcher OpusUsageChip):
Normal:
V5 quota: 97.3% left, ~1683 free 1MP images (…quota refills over time…)Overdrawn:
V5 quota: overdrawn (V5 generation bills Anlas at normal price; quota refills over time and restores freeness once back above zero)Source: the
usagefield of/user/subscription(percent/isNegative/timeUntilNextPercent); refills above 100% are shown as-is; not appended for non-Opus or on query failure
Tag database & semantic search
The vocabulary is built by tool/build_tag_vector_db.py (priority matches the Launcher: hand-edited Chinese > full ffdkj Chinese):
tag_catalog.db: tag list, aliases (37,790 entries), and hand-edited Chinese. Auto-fetched by default: reads the Launcher repo's
assets/databases/manifest.jsonon the main branch, downloads the official release asset, and verifies it against the manifest's SHA-256/size, cached attool/.tmp/tag_catalog.db(that file is LFS inside the repo, so raw downloads only fetch a pointer — hence going through release). Pass--source <path>to use a local file offlineffdkj Chinese translation table (
--with-ffdkj, recommended): full 320k-entry Chinese set. Downloads the URL pinned in Launcherzh_dictionary_download.dart, verified against a fixed SHA-256, cached astool/.tmp/ffdkj_tag.sqlite
The server picks the database via env NAI_TAG_DB (default tag_vectors.db in the project root).
# Build the vocabulary
.venv/Scripts/python tool/build_tag_vector_db.py --db tag_vectors.db --with-ffdkj
# Fill embeddings (enables semantic search; no args fills every unfilled row, batchable)
$env:NAI_EMBEDDING_URL = "https://your-embeddings-endpoint"
$env:NAI_EMBEDDING_MODEL = "text-embedding-xxx"
$env:NAI_EMBEDDING_API_KEY = "..." # optional
.venv/Scripts/python tool/fill_tag_vectors.pyfill_tag_vectors.py performance: requests packed to the model's token limit + concurrency. Defaults assume a 32k-input model: NAI_EMBED_BATCH_TOKENS=24000, NAI_EMBED_CHARS_PER_TOKEN=1.0, NAI_EMBED_CONCURRENCY=4; script flags --min-post-count / --max-rows let you fill hot tags first; 429/5xx exponential backoff; when responses carry index, results are written back by index. Order of magnitude: 220k rows ≈ 200 requests, tens of minutes at 4-way concurrency. tool/mock_embeddings_server.py validates the pipeline offline.
Before vectors are filled, search_tag does Chinese/alias/literal matching (~0.1s); once embeddings are configured, cosine semantic search switches on automatically (e.g. "facing the viewer" → looking at viewer; the vectors form a single numpy float32 matmul, so latency is dominated by the 1–4s embeddings network round-trip). Falls back to pure Python if numpy is missing.
Environment variables
Variable | Purpose | Default |
| NovelAI token (required) | — |
| Workflow directory |
|
| Image output directory |
|
| Tag database path | project-root |
| embeddings endpoint (shared by server and filler script) | — |
| filler performance tuning | 24000 / 1.0 / 4 |
Verification
.venv/Scripts/python smoke_test.py — fully offline: stdio handshake, all 18 tools, workflow create/read/delete flow, Anlas estimation & V5 quota formatting, character/source-image/mask/precise-reference setup, tag search, and error paths (no network, no billing).
Reference implementation: Aaalice_NAI_Launcher
Large parts of this project are ported from the reference project Aaalice233/Aaalice_NAI_Launcher (a Flutter desktop client), mirroring the public behavior of its internals:
Anlas billing formula & Opus free-tier judgment —
AnlasCalculatormodern formula, cloud upscaling tiersModel sampling presets, UC quality tags/preset texts, inpainting variant mapping —
ModelCapabilities/ImageModelsV5 Opus quota pool caliber & display (1% ≈ 17.3 images, overdraw semantics, refill) —
OpusUsageInfo//user/subscriptionparsing /OpusUsageChipTag vocabulary & Chinese translation sources, pinned-hash verification —
tool/tag_catalog/andzh_dictionary_download.dart
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Generate, edit and upscale images with references, batch jobs, cost previews and original downloads.
Official AI/ML API server: 10,000+ AI tools and models for chat, image, video, audio, search, data.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Generate images, videos and music with model discovery, cost estimates and asynchronous results.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to generate images using NovelAI, supporting text-to-image, image-to-image, and tag suggestions.3MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that exposes NovelAI image generation as tools for AI agents, supporting txt2img, img2img, inpaint, upscaling, Director tools, ControlNet annotation, tag suggestions, vibe encoding, and subscription queries via stdio or streamable-http transports.12MIT
- AlicenseBqualityCmaintenanceEnables AI assistants to generate and edit images via NovelAI, supporting text-to-image, img2img, inpainting, Director Tools, upscaling, Vibe Transfer, and tag suggestions.7MIT
- AlicenseAqualityBmaintenanceExposes a local Forge or AUTOMATIC1111 SDXL backend as typed image-generation tools, enabling any MCP client to generate and edit images through a deterministic, stateless interface with server-enforced SFW content.3Mozilla Public 2.0