NovelAI Image MCP
Generate and edit NovelAI images from an AI agent: txt2img, inpaint, upscale, ControlNet
- 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-mcpAdd 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/accountRequiredNOVELAI_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

HyperFrames by HeyGen
MCP serverHosted MCP connector for creating and rendering videos from HTML through AI chat
- Remote
- Freemium
- 85.3K GitHub stars
- Design and media

ffmpeg-skill
MCP serverLocal FFmpeg video and audio editing tools for coding agents over MCP
Runs locally- Open source
- 6.9K GitHub stars
- Design and media

Generate fictional character portraits and lip-synced talking videos from text over MCP
- 10 tools
- Remote
- Freemium
- Design and media

ChartAnt
MCP serverRemote MCP server returning charts, maps and dashboards as hosted PNG links
- 51 tools
- Remote
- Freemium
- Design and media

VfxSmith
MCP serverSearch, generate, refine and export pixel art game effects from Claude Code or Codex
Not checked yet- Remote
- Freemium
- Design and media
Eikino
MCP serverEstimate where photos or video frames were taken and check media for AI generation
- 3 tools
- Remote
- Freemium
- Security