How do I use NovelAI Image MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@NovelAI Image MCP Create an image of a cozy cabin in a snowy forest at twilight" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

NovelAI Image MCP

by xinvxueyuan

Overview Schema Related Servers Score Discussions

Python

Hybrid

NovelAI Image MCP

Docs License: MIT Python 3.13+ REUSE status DeepWiki skills.sh

An MCP (Model Context Protocol) server that exposes NovelAI image generation as tools for AI agents (Claude Desktop, Cline, custom agents, remote clients).

Built on the official MCP Python SDK v2 (MCPServer), it lets an agent generate images (txt2img / img2img / inpaint), upscale, run Director tools (line art, emotion, background removal, …), annotate with ControlNet, suggest tags, encode vibes, and query account subscription — all through the standard MCP tool interface.

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

Features

11 MCP tools covering the full NovelAI image API surface.
Two transports: stdio (local agents) + streamable-http (remote / multi-client).
Dual image return: base64 Image content blocks (the agent sees the image) and PNG saved to disk (path returned as text).
Async + sync: async tool handlers + a typer CLI for direct invocation.
Monorepo: uv workspace (Python) + pnpm workspace (Node tooling) orchestrated by Turbo; MIT-licensed, Docker-ready, GitHub Pages docs.

Related MCP server: comfyui-mcp-server-node

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
├── .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.

Quick start

Install 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=streamable-http uv run python -m novelai_image_mcp serve
#   → http://127.0.0.1:8000/mcp

Install from 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": ["--prerelease=allow", "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).

CLI (sync, for scripting)

uv run python -m novelai_image_mcp generate --prompt "a cat, masterpiece" --width 832 --height 1216
uv run python -m novelai_image_mcp upscale --image ./in.png --factor 4
uv run python -m novelai_image_mcp info          # subscription / Anlas balance
uv run python -m novelai_image_mcp --help

Tools

Tool	Description
`generate_image`	Text-to-image (V3 / V4 / V4.5 models, character prompts, vibes)
`image_to_image`	Image-to-image with strength/noise
`inpaint`	Inpainting (requires an inpaint model + mask)
`upscale_image`	2× / 4× upscale
`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
`MCP_TRANSPORT`	`stdio`	`stdio` or `streamable-http`
`MCP_HOST` / `MCP_PORT`	`127.0.0.1` / `8000`	For streamable-http

NovelAI API reference: https://image.novelai.net/docs/index.html

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: https://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).

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

0dRelease cycle

7Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

imagegen-mcp
AI & Machine Learning Image & Video Processing
spartanz51
A
license
-
quality
D
maintenance
MCP server that wraps OpenAI's image generation and editing APIs, enabling text-to-image and image-to-image operations via tools.
Last updated 2025-05-02
613
37
ISC
comfyui-mcp-server-node
AI & Machine Learning Image & Video Processing Multimedia Processing
yar3333
A
license
-
quality
C
maintenance
A lightweight MCP server that bridges AI agents with a local ComfyUI instance to generate and iteratively refine images, audio, and video through conversational tool calls.
Last updated 2026-07-31
30
MIT
image-forge-mcp
Image & Video Processing AI & Machine Learning
Cheng77c
F
license
-
quality
D
maintenance
An MCP server for AI-powered image processing (generate, edit, vary, analyze) supporting OpenAI, Gemini, Ideogram, and custom relay endpoints.
Last updated 2026-03-03
fm-mcp-comfyui-bridge
Image & Video Processing AI & Machine Learning
rerofumi
A
license
-
quality
D
maintenance
MCP server that provides image generation, captioning, and tagging via ComfyUI API, configurable for agent tools.
Last updated 2025-07-12
3
MIT

View all related MCP servers

Related MCP Connectors

mcp-flux-pro
MCP server for Flux AI image generation
mcp-nanobanana-pro
MCP server for NanoBanana AI image generation and editing
mcp-aichat
MCP server for AI dialogue using various LLM models via AceDataCloud

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/xinvxueyuan/NovelAI-Image-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

NovelAI Image MCP

Features

Repository layout

Quick start

Install from source (development)

Install from PyPI (runtime only)

Optional: Node tooling (contributors)

Connect an agent

stdio (local agent — Claude Desktop / Cline)

Alternative: uvx (published package)

http (remote / Docker deployment)

CLI (sync, for scripting)

Tools

Configuration

Development

Docker

Documentation

License

Maintenance

Resources

Looking for Admin?

Related MCP Servers

imagegen-mcp

comfyui-mcp-server-node

image-forge-mcp

fm-mcp-comfyui-bridge

Related MCP Connectors

Latest Blog Posts

MCP directory API