This MCP server exposes NovelAI image generation capabilities as tools for AI agents. It provides operations including txt2img, img2img, inpaint, upscale, Director, and ControlNet, enabling integration of NovelAI image workflows into MCP-compatible applications.
๐ ๏ธ Key Features
Tooling for NovelAI image generation via MCP
Supports: txt2img, img2img, inpaint, upscale
Includes Director and ControlNet-related tools
๐ Use Cases
Generating images from text with txt2img
Transforming existing images using img2img
Editing images using inpaint
Improving image resolution via upscale
Using Director and ControlNet in image generation pipelines
โก Developer Benefits
Standardized access to NovelAI image generation through MCP tools
Designed for AI agent integration (e.g., Claude Desk mentioned in the excerpt)
Repository includes documentation and MIT licensing (per badges in excerpt)
โ ๏ธ Limitations
The provided excerpt lists tool names and scope but does not include usage details, authentication, or configuration specifics.
An MCP (Model Context Protocol) server that exposes NovelAI image
generation to AI agents (Claude Desktop, Cline, custom agents, remote
clients), plus a sync CLI and three skills.sh packages that teach
those agents how to drive either surface.
Built on FastMCP 4 (the fastmcp framework over the MCP SDK v2 mcp>=2.3.0),
it covers txt2img / img2img / inpaint, 4ร upscale, Director tools (line art,
emotion, background removal, โฆ), ControlNet annotation, tag suggestions, vibe
encoding and account subscription โ all through the standard MCP tool
interface.
All three wrap the same async NovelAIClient; they differ in how you invoke
it.
MCP tools โ interactive agent sessions (Claude Desktop, Cline, โฆ). The
agent sees base64 Image content blocks.
CLI โ shell scripting, CI jobs, one-off commands. Saves a PNG and prints
its path; no image blocks.
Agent skills โ portable instructions that tell an agent how to use the
other two. They inherit the mode they drive.
Features
11 MCP tools covering the full NovelAI image API surface.
2 prompts + 3 resources + 1 resource template: house-style prompt drafting and tool sequencing
(novelai_prompt_writer, novelai_image_workflow), plus novelai://models,
novelai://samplers, novelai://defaults and novelai://outputs/{name} for
discovering the model/sampler vocabulary and reading generated PNGs back.
Three agent skills (novelai-cli, novelai-mcp-tools,
novelai-workflows) grouped as CLI / MCP Tools / Workflows, installable with
one npx skills add command.
A sync typer CLI with six subcommands for scripting outside an MCP host.
Two transports: stdio (local agents) + HTTP (remote / multi-client), the
latter optionally protected by a bearer token (MCP_AUTH_TOKEN).
Opt-in routing and audit (HTTP): a client that sends X-MCP-Insiders
gets per-route output directories, per-route loggers and an append-only JSONL
audit trail (prompts and credentials are never written verbatim). Without the
header nothing changes. See
Insiders header, routing and audit.
Structured results: enum-validated tool schemas, MCP tool annotations and
ToolError for expected failures.
Dual image return: base64 Image content blocks (the agent sees the image)
and PNG saved to disk (path returned as text).
--yes skips the interactive picker; --global installs to
~/.agents/skills/ so every project on the machine can use them. Drop
--global to install into the current project's .agents/skills/ instead.
See Agent skills for what each skill covers.
2. Install the server (from source, development)
bash
# 1. Clone
git clone https://github.com/xinvxueyuan/NovelAI-Image-MCP.git
cd NovelAI-Image-MCP
# 2. Sync the uv workspace (installs server + docs + dev tools)
uv sync# 3. Configure credentialscp .env.example .env# set NOVELAI_TOKEN=... (preferred)# or NOVELAI_USERNAME + NOVELAI_PASSWORD# 4. Run (stdio โ for local agents)
uv run python -m novelai_image_mcp serve
# 5. Or over HTTP
MCP_TRANSPORT=http uv run python -m novelai_image_mcp serve
# โ http://127.0.0.1:8000/mcp
This wires the husky pre-commit + commit-msg hooks and gives you turbo /
markdownlint-cli2 for local development. The MCP server has zero Node
runtime dependencies โ this step is only for contributors.
Connect an agent
The MCP server supports two transports (stdio + http), all configured under
mcpServers:
Replace http://127.0.0.1:8000/mcp with your self-deployed endpoint (e.g.
https://mcp.example.com/mcp behind a TLS-terminating reverse proxy). Swap
the literal token placeholder for a host-managed secret reference if your
MCP host supports one (Claude Desktop, Cline, etc. expose this via their
own secrets UI).
Standard FastMCP entry points
The repository ships a fastmcp.json whose source points at
apps/server/mcp_server.py, so plain FastMCP tooling works too (run from the
repository root, after uv sync):
bash
uv run fastmcp run fastmcp.json # stdio server
uv run fastmcp inspect # list tools/prompts/resources
uv run --directory apps/server fastmcp dev inspector mcp_server.py # Inspector
fastmcp.json has no environment block on purpose: the workspace virtualenv
already has the package installed, and an environment entry would make
FastMCP build a second, throwaway environment for every run.
CLI (sync, for scripting)
The CLI exposes six subcommands: serve, generate, upscale, director,
annotate, info.
bash
# Run the MCP server (stdio by default; -t http for the HTTP transport)
novelai-image-mcp serve
# Text-to-image โ prints one absolute PNG path per generated image
novelai-image-mcp generate --prompt "a cat, masterpiece" --width 832 --height 1216
# 4x upscale (V5 model only)
novelai-image-mcp upscale --image ./in.png --factor 4
# Director tools: lineart | sketch | bg-removal | declutter | colorize | emotion
novelai-image-mcp director lineart ./photo.png --defry 5
# ControlNet annotation: hed | midas | fake_scribble | mlsd | uniformer
novelai-image-mcp annotate ./photo.png --model hed
# Subscription / Anlas balance
novelai-image-mcp info
novelai-image-mcp --help
Install it with pip install novelai-image-mcp, run it ad hoc with
uvx novelai-image-mcp <command>, or from the monorepo with
uv run --directory apps/server novelai-image-mcp <command>. Every
image-producing command saves a PNG to NOVELAI_OUTPUT_DIR (default
outputs) and prints its path; -o / --output-dir overrides the
directory for one invocation. The full flag list lives in the
novelai-cli skill.
Agent skills
Three skills.sh packages ship in skills/. They teach AI
agents (Claude Code, Codex, GitHub Copilot, Cursor, โฆ) how to drive the CLI and
the MCP tools, so you do not have to paste docs into the conversation.
graph TD
Q{How will you drive NovelAI?}
Q -->|"Interactive session with an MCP host"| MCP["MCP tools<br/>11 tools over stdio / http"]
Q -->|"Shell script, CI job, one-off command"| CLI["CLI<br/>novelai-image-mcp generate ..."]
Q -->|"Let an agent pick the right one"| SK["Agent skills<br/>novelai-cli / novelai-mcp-tools / novelai-workflows"]
SK --> MCP
SK --> CLI
The 11 MCP tools โ model selection, parameters, return shape, Anlas cost
novelai-workflows
Workflows
Multi-step creative pipelines (txt2imgโupscale, annotateโimg2img, Director edits)
Skills and the CLI/MCP tools are complementary, not either/or: install all
three and the agent picks the mode that fits the task. Each skill points at the
other two instead of repeating them. See the Agent skills docs
for the group descriptions and a mode-comparison table.
JSON lists of routing candidates, first non-empty wins
MCP_INSIDERS_DISABLED_FEATURES
[]
Operator kill switch (JSON list), wins over any client
MCP_ROUTE_SCOPED_OUTPUT
true
Write images under <output>/<route>/ while routing is active
MCP_AUDIT_LOG_PATH
<output>/audit.jsonl
Append-only JSONL audit trail
MCP_LOG_LEVEL
โ
DEBUG/INFO/WARNING/ERROR/CRITICAL
List- and dict-valued settings are read as JSON: MCP_MODEL_HEADERS='["X-MCP-Model"]'
works, while A,B raises a settings error and an empty value is not valid JSON.
Routing candidate defaults (JSON lists, first non-empty header wins):
The server then writes that request's images under
<NOVELAI_OUTPUT_DIR>/team-a/, emits one line to the
novelai_image_mcp.audit.team-a logger, and appends one record to the audit
JSONL (the record keeps a prompt's length and a truncated SHA-256, never the
prompt, and never a credential header or an image payload).
Nothing changes without the header -- no scoped directory, no audit file, no
tool added or removed -- with one deliberate exception: director_tool's
emotion and emotion_level parameters now require the opt-in and fail with a
ToolError otherwise (see the CHANGELOG). Routing headers are client-supplied
and forgeable, so grant the opt-in only behind a trusted gateway.