NovelAI Image MCP

NovelAI image generation as MCP tools: txt2img, img2img, inpaint, upscale, Director, ControlNet.

What can you do with NovelAI Image MCP?

11 MCP tools covering the full NovelAI image API surface.
2 prompts + 3 resources + 1 resource template: house-style prompt drafting and tool sequencing
Three agent skills (novelai-cli, novelai-mcp-tools,
A sync typer CLI with six subcommands for scripting outside an MCP host.
Two transports: stdio (local agents) + HTTP (remote / multi-client), the
Opt-in routing and audit (HTTP): a client that sends X-MCP-Insiders
Structured results: enum-validated tool schemas, MCP tool annotations and
Dual image return: base64 Image content blocks (the agent sees the image)

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package novelai-image-mcp

Claude Code

claude mcp add novelai-image-mcp -e 'NOVELAI_TOKEN=<your novelai_token>' -- uvx novelai-image-mcp==0.7.0

JSON configuration (Claude Desktop, Cursor, VS Code)

{
    "mcpServers": {
        "novelai-image-mcp": {
            "command": "uvx",
            "args": [
                "novelai-image-mcp==0.7.0"
            ],
            "env": {
                "NOVELAI_TOKEN": "<your novelai_token>"
            }
        }
    }
}

Environment variables

NOVELAI_TOKEN required secret NovelAI persistent API token (preferred auth). Get from https://novelai.net/account

OCI package ghcr.io/xinvxueyuan/novelai-image-mcp:0.7.0

Claude Code

claude mcp add novelai-image-mcp -e 'NOVELAI_TOKEN=<your novelai_token>' -- docker run -i --rm ghcr.io/xinvxueyuan/novelai-image-mcp:0.7.0

JSON configuration (Claude Desktop, Cursor, VS Code)

{
    "mcpServers": {
        "novelai-image-mcp": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "ghcr.io/xinvxueyuan/novelai-image-mcp:0.7.0"
            ],
            "env": {
                "NOVELAI_TOKEN": "<your novelai_token>"
            }
        }
    }
}

Environment variables

NOVELAI_TOKEN required secret NovelAI persistent API token (preferred auth). Get from https://novelai.net/account

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents

NovelAI Image MCP
Languages
Three ways to drive it
Features
Quick start
Connect an agent
CLI (sync, for scripting)
Agent skills
Repository layout
Tools
Configuration
Development
Documentation
License
Links

NovelAI Image MCP

Languages

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

[![CI][ci-badge]][ci-workflow] [![Docs][docs-badge]][docs] [![License: MIT][mit-badge]][license] [![Python 3.13+][python-badge]][python] [![uv][uv-badge]][uv] [![REUSE status][reuse-badge]][reuse] [![DeepWiki][deepwiki-badge]][deepwiki] [![skills.sh][skills-badge]][skills-sh]

[![NovelAI Image MCP - MCP server for integrating NovelAI Image generation into AI | Product Hunt][product-hunt-badge]][product-hunt] [![Featured on Lifto][lifto-badge]][lifto]

An [MCP (Model Context Protocol)][mcp] server that exposes NovelAI image generation to AI agents (Claude Desktop, Cline, custom agents, remote clients), plus a sync CLI and three [skills.sh][skills-site] 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][docs]

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][insiders-docs].
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][skills-docs].

Agent skills

Three [skills.sh][skills-site] 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][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][contributing] for the developer guide and [apps/docs/source/][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][tools-docs] 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][insiders-docs].

NovelAI API reference: [image.novelai.net/docs][nai-docs]

Development

The project is a uv + pnpm monorepo orchestrated by Turbo. See [CONTRIBUTING.md][contributing] 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][dockerfile] but the build context is the repository root (so uv can resolve the workspace graph). See [docker-compose.yml][docker-compose].

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][docs]
Source: [apps/docs/source/][docs-source]
Build locally: pnpm docs:serve

License

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

Links

[ci-badge]: https://github.com/xinvxueyuan/NovelAI-Image-MCP/actions/workflows/ci.yml/badge.svg [ci-workflow]: https://github.com/xinvxueyuan/NovelAI-Image-MCP/actions/workflows/ci.yml [docs-badge]: https://github.com/xinvxueyuan/NovelAI-Image-MCP/actions/workflows/docs.yml/badge.svg [mit-badge]: https://img.shields.io/badge/License-MIT-blue.svg [python-badge]: https://img.shields.io/badge/python-3.13+-blue.svg [uv-badge]: https://img.shields.io/badge/uv-managed-261230.svg [reuse-badge]: https://api.reuse.software/badge/github.com/xinvxueyuan/NovelAI-Image-MCP [deepwiki-badge]: https://img.shields.io/badge/DeepWiki-Ask%20DeepWiki-blue [skills-badge]: https://skills.sh/b/xinvxueyuan/NovelAI-Image-MCP [product-hunt-badge]: https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1206099&theme=light&t=1784973837616 [lifto-badge]: https://liftoapp.com/badges/featured-light.svg

[docs]: https://xinvxueyuan.github.io/NovelAI-Image-MCP/ [reuse]: https://api.reuse.software/info/github.com/xinvxueyuan/NovelAI-Image-MCP [python]: https://www.python.org/downloads/ [uv]: https://docs.astral.sh/uv/ [deepwiki]: https://deepwiki.com/xinvxueyuan/NovelAI-Image-MCP [skills-sh]: https://skills.sh/xinvxueyuan/NovelAI-Image-MCP [product-hunt]: https://www.producthunt.com/products/novelai-image-mcp?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-novelai-image-mcp [lifto]: https://liftoapp.com/product/novelai-image-mcp [mcp]: https://modelcontextprotocol.io/ [contributing]: CONTRIBUTING.md [docs-source]: apps/docs/source/ [skills-site]: https://skills.sh [skills-docs]: https://xinvxueyuan.github.io/NovelAI-Image-MCP/skills.html [tools-docs]: https://xinvxueyuan.github.io/NovelAI-Image-MCP/tools/index.html [insiders-docs]: https://xinvxueyuan.github.io/NovelAI-Image-MCP/development/insiders-and-routing.html [nai-docs]: https://image.novelai.net/docs/index.html [dockerfile]: apps/server/Dockerfile [docker-compose]: docker-compose.yml [license]: LICENSE [reuse-toml]: REUSE.toml [dco]: https://developercertificate.org/

Frequently asked questions

What is NovelAI Image MCP?

NovelAI image generation as MCP tools: txt2img, img2img, inpaint, upscale, Director, ControlNet.

How do I install NovelAI Image MCP?

It runs on your machine. In Claude Code: claude mcp add novelai-image-mcp -e 'NOVELAI_TOKEN=<your novelai_token>' -- uvx novelai-image-mcp==0.7.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does NovelAI Image MCP need an API key?

Yes. It expects NOVELAI_TOKEN, which you set in its configuration.

Is NovelAI Image MCP open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains NovelAI Image MCP?

It is published by xinvxueyuan. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.

Server details

Listed in: Official MCP Registry
Publisher: xinvxueyuan
Category: Media and design
Runs: Local
GitHub stars: ★ 12
License: MIT
Language: Python
Last commit: Oct 25, 2026
Open issues: 2
Version: 0.7.0
Published: Oct 22, 2026

io.github.xinvxueyuan/novelai-image-mcp

Similar servers

onsystem Catches palette colors, native elements and APIs your design system lacks in agent-writ...
Remove AI Watermarks Identify and remove AI watermarks and provenance metadata from your own images and video.
FrameOS Turn long videos into captioned, reframed short clips, thumbnails, and social posts.
Apolo Optimize, convert and compare images locally: WebP, AVIF, JPEG XL, JPEG and PNG.
mcp-video Compatibility package: mcp-video now installs Kinocut (formerly mcp-video).
Kinocut Guardrailed video editing for AI agents: FFmpeg, captions, effects, Hyperframes, and re...
Clipform Interactive video forms that capture authentic responses. Build engaging forms in minutes.
Sonilo Music & Sound Effects Licensed soundtracks and sound effects matched to your video. Commercial use OK.

Media and design