NovelAI Image MCP

NovelAI Image MCP

Languages

English	简体中文	日本語
English	简体中文	日本語

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.

📖 Documentation: xinvxueyuan.github.io/NovelAI-Image-MCP

Three ways to drive it

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).
• Monorepo: uv workspace (Python) + pnpm workspace (Node tooling) orchestrated by Turbo; MIT-licensed, Docker-ready, GitHub Pages docs.

Quick start

1. Install the agent skills

npx skills add --yes --global xinvxueyuan/NovelAI-Image-MCP

--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)

# 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 credentials
cp .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

3. Install the server (PyPI, runtime only)

pip install novelai-image-mcp
export NOVELAI_TOKEN=pst-...
novelai-image-mcp serve

Optional: Node tooling (contributors)

If you plan to contribute, install the cross-cutting Node toolchain (turbo, husky, markdownlint) via pnpm:

corepack enable pnpm      # one-time
pnpm install --frozen-lockfile

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:

stdio (local agent — Claude Desktop / Cline)

claude_desktop_config.json:

{
  "mcpServers": {
    "novelai-image": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/NovelAI-Image-MCP",
        "python",
        "-m",
        "novelai_image_mcp",
        "serve"
      ],
      "env": {
        "NOVELAI_TOKEN": "${input:novelai_token}"
      }
    }
  }
}

Alternative: uvx (published package)

{
  "mcpServers": {
    "novelai-image": {
      "command": "uvx",
      "args": ["novelai-image-mcp", "serve"],
      "env": { "NOVELAI_TOKEN": "pst-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Set NOVELAI_TOKEN (or NOVELAI_USERNAME + NOVELAI_PASSWORD) in the host environment before launching — uvx inherits the parent shell env.

http (remote / Docker deployment)

After docker compose up --build (server listens on http://HOST:8000/mcp):

{
  "mcpServers": {
    "novelai-image-http": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer pst-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

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):

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.

# 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.

npx skills add --yes --global xinvxueyuan/NovelAI-Image-MCP

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

Skill	Group	What it teaches
novelai-cli	CLI	Typer CLI commands (serve, generate, upscale, director, annotate, info) for shell scripting
novelai-mcp-tools	MCP Tools	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.

Repository layout

This is a uv + pnpm monorepo:

NovelAI-Image-MCP/
├── apps/
│   ├── server/                 # MCP server (the installable PyPI package)
│   │   ├── src/novelai_image_mcp/   # 11 MCP tools + NovelAI HTTP client
│   │   ├── tests/
│   │   ├── docker/              # smoke-test entrypoint
│   │   ├── Dockerfile           # built with repo root as context
│   │   └── pyproject.toml       # ruff / pyright / pytest config
│   └── docs/                    # Sphinx documentation site
│       ├── source/              # MyST Markdown + conf.py
│       ├── Makefile
│       └── pyproject.toml
├── skills/                      # skills.sh packages (novelai-cli, ...)
├── skills.sh.json               # skill groupings for skills.sh
├── .github/                     # workflows, CODEOWNERS, issue templates
├── pyproject.toml               # uv workspace root (virtual)
├── uv.lock                      # single shared lockfile
├── pnpm-workspace.yaml          # pnpm workspace declaration
├── pnpm-lock.yaml               # Node toolchain lockfile
├── turbo.json                   # cross-workspace task graph
├── package.json                 # root scripts + dev toolchain
└── docker-compose.yml           # local container orchestration

See CONTRIBUTING.md for the developer guide and apps/docs/source/ for the full documentation source.

Tools

Tool	Description
generate_image	Text-to-image (V3 / V4 / V4.5 / V5 models, character prompts; vibes V4/V4.5 only)
image_to_image	Image-to-image with strength/noise
inpaint	Inpainting (requires an inpaint model + mask)
upscale_image	4× upscale (V5 model)
director_tool	Line art / sketch / bg-removal / declutter / colorize / emotion
annotate_image	ControlNet annotation (hed, midas, scribble, mlsd, uniformer)
suggest_tags	Prompt tag suggestions
encode_vibe	Encode a reference image into a vibe token
get_subscription	Account subscription + Anlas balance
get_user_data	Account user data
estimate_anlas_cost	Estimate Anlas cost for a generation (no API call)

See the tools reference on the docs site for parameters and examples.

Configuration

All settings are environment variables (see .env.example). Key ones:

Variable	Default	Notes
NOVELAI_TOKEN	—	Persistent API token (preferred auth)
NOVELAI_USERNAME / NOVELAI_PASSWORD	—	Access-key login (argon2id)
NOVELAI_OUTPUT_DIR	outputs	Where generated PNGs are saved
NOVELAI_DEFAULT_MODEL	nai-diffusion-4-5-full	Model id used when a tool call omits one
NOVELAI_DEFAULT_WIDTH / NOVELAI_DEFAULT_HEIGHT	832 / 1216	Default image size
NOVELAI_DEFAULT_STEPS	28	Default sampling steps (1–50)
NOVELAI_DEFAULT_SCALE	5.0	Default CFG scale (≤20)
NOVELAI_DEFAULT_SAMPLER	k_euler_ancestral	Default sampler
NOVELAI_UPSCALE_MODEL	nai-diffusion-5-full	Model for the standalone 4× upscaler (V5 line only)
NOVELAI_TIMEOUT	120	HTTP timeout in seconds
NOVELAI_IMAGE_BASE_URL	https://image.novelai.net	Consolidated API host for generation and account endpoints
NOVELAI_LEGACY_IMAGE_BASE_URL	https://api.novelai.net	Primary API host; only /ai/annotate-image still uses it
MCP_TRANSPORT	stdio	stdio or http (streamable-http is a legacy alias)
MCP_HOST / MCP_PORT / MCP_PATH	127.0.0.1 / 8000 / /mcp	For the HTTP transport
MCP_AUTH_TOKEN	—	When set, the HTTP transport requires Authorization: Bearer <token>
MCP_ROUTE_TOKENS	—	JSON {"<route>": "<token>"} route-bound bearer tokens (401 on route mismatch)
MCP_INSIDERS_HEADER	X-MCP-Insiders	Header a client opts in with (HTTP only)
MCP_MODEL_HEADERS / MCP_AGENT_HEADERS / MCP_CLIENT_HEADERS	see below	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):

• MCP_MODEL_HEADERS — ["X-MCP-Model", "X-MCP-Model-Name"]
• MCP_AGENT_HEADERS — ["X-MCP-Agent-ID", "X-MCP-Agent", "X-MCP-Agent-Source"]
• MCP_CLIENT_HEADERS — ["X-MCP-Client", "X-MCP-Client-Session-Id"]

Insiders header and routing

Over HTTP a client can opt in to experimental behaviour and declare which route, model, agent and session a request belongs to:

X-MCP-Insiders: true
X-MCP-Agent-ID: team-a
X-MCP-Model: nai-diffusion-5-full

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.

Full contract: Insiders header, routing and audit.

NovelAI API reference: image.novelai.net/docs

Development

The project is a uv + pnpm monorepo orchestrated by Turbo. See CONTRIBUTING.md for the full setup; the short version:

uv sync                              # Python workspace (server + docs + dev)
pnpm install --frozen-lockfile       # Node toolchain (turbo + husky + markdownlint)

pnpm check                           # lint + typecheck + test (all workspaces)
pnpm docs:build                       # build the docs site
pnpm server:serve                     # run the MCP server
pnpm docs:serve                       # sphinx-autobuild with live reload

Per-member commands (via uv):

uv run --directory apps/server ruff check src tests    # lint
uv run --directory apps/server -m pyright              # typecheck
uv run --directory apps/server -m pytest               # tests

Docker

docker compose up --build      # builds and runs the server (HTTP transport)

The Dockerfile lives at apps/server/Dockerfile but the build context is the repository root (so uv can resolve the workspace graph). See docker-compose.yml.

Documentation

The Sphinx documentation site is built with Furo + MyST Markdown and auto-deploys to GitHub Pages on every push to main:

• Live site: xinvxueyuan.github.io/NovelAI-Image-MCP
• Source: apps/docs/source/
• Build locally: pnpm docs:serve

License

MIT — see LICENSE. Per-file SPDX annotations live in REUSE.toml. Contributions are subject to the Developer Certificate of Origin (the commit-msg hook signs off commits automatically).

Links