Skip to content
MCP server

NovelAI Image MCP

Generate and edit NovelAI images from an AI agent: txt2img, inpaint, upscale, ControlNet

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.7.1
Listing updated
3 days ago

About NovelAI Image MCP

NovelAI Image MCP is an open-source MCP server for design and media. It runs locally on your machine and is started by your AI client.

The work is split across 11 tools covering the NovelAI image API, plus two prompts, three resources and a resource template that list models, samplers and defaults. Images come back in two ways: base64 image blocks so the agent can see the result, and a PNG saved to disk with its path returned as text.

Beyond plain generation it supports img2img, inpainting, 4x upscaling, Director tools such as line art, emotion and background removal, ControlNet annotation, tag suggestions, vibe encoding and an account subscription query. It runs over stdio for local agents or streamable HTTP for remote use, optionally guarded by a bearer token. An opt-in header adds per-route output folders and a JSONL audit trail.

A NovelAI persistent API token is required (NOVELAI_TOKEN), so you need your own NovelAI account. It is built on FastMCP, MIT licensed, available on PyPI and as a Docker image, and also ships a CLI and three agent skills.

Install

Run in a terminal

claude mcp add novelai-image-mcp --env NOVELAI_TOKEN='<NOVELAI_TOKEN>' -- uvx novelai-image-mcp

Add to claude_desktop_config.json

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

Add to ~/.cursor/mcp.json

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

Add to .vscode/mcp.json

{
  "servers": {
    "novelai-image-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "novelai-image-mcp"
      ],
      "env": {
        "NOVELAI_TOKEN": "<NOVELAI_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Configuration

  • NOVELAI_TOKENNovelAI persistent API token (preferred auth). Get from https://novelai.net/accountRequired
  • NOVELAI_TOKENNovelAI persistent API token (preferred auth). Get from https://novelai.net/accountRequired

Tools this server provides (5)

Taken from the project documentation; the running server may differ.

upscale_image
Upscale an image 4x.
director_tool
Run Director tools such as line art, emotion and background removal.
annotate_image
Annotate an image with ControlNet preprocessors.
suggest_tags
Suggest tags for a prompt.
encode_vibe
Encode an image as a vibe for transfer.

What it does

Full image toolset
Text-to-image, image-to-image and inpainting.
Director tools
Line art, emotion, background removal and similar edits.
Upscale and annotate
4x upscaling and ControlNet annotation.
Vibe and tag helpers
Encode vibes and suggest tags.
Two transports
stdio for local agents, streamable HTTP for remote clients.
Dual output
Images returned to the agent and saved as PNG files.

Good for

  • Let an agent draft illustrations and iterate on them
  • Fix part of an image with inpainting
  • Upscale a generated image
  • Script batch generation from a CLI or CI job

Pricing

Open source

MIT licensed; requires your own NovelAI account token

Prices change. Check xinvxueyuan.github.io before you buy.

NovelAI Image MCP FAQ

What credentials are needed?

A NovelAI persistent API token set as NOVELAI_TOKEN.

How do I install it?

From PyPI as novelai-image-mcp, or from the ghcr.io Docker image.

What licence is it?

MIT.

Can it run remotely?

Yes, over streamable HTTP, optionally with a bearer token.

Is NovelAI Image MCP free?

Yes. NovelAI Image MCP is open source, so you can use and self-host it for free.

How do I add NovelAI Image MCP to Claude Code?

Run this command in your terminal: claude mcp add novelai-image-mcp --env NOVELAI_TOKEN='<NOVELAI_TOKEN>' -- uvx novelai-image-mcp

What are the best alternatives to NovelAI Image MCP?

The closest alternatives to NovelAI Image MCP are HyperFrames by HeyGen, ffmpeg-skill, AvatarSay — Fictional Character & Talking Video MCP, ChartAnt and VfxSmith.

Alternatives to NovelAI Image MCP

  1. Hosted MCP connector for creating and rendering videos from HTML through AI chat

    • Remote
    • Freemium
    • 85.3K GitHub stars
    • Design and media
  2. ffmpeg-skill

    MCP server

    Local FFmpeg video and audio editing tools for coding agents over MCP

    Runs locally
    • Open source
    • 6.9K GitHub stars
    • Design and media
  3. ChartAnt

    MCP server

    Remote MCP server returning charts, maps and dashboards as hosted PNG links

    • 51 tools
    • Remote
    • Freemium
    • Design and media
  4. VfxSmith

    MCP server

    Search, generate, refine and export pixel art game effects from Claude Code or Codex

    Not checked yet
    • Remote
    • Freemium
    • Design and media
  5. Eikino

    MCP server

    Estimate where photos or video frames were taken and check media for AI generation

    • 3 tools
    • Remote
    • Freemium
    • Security