NovelAI.ImageGen.Mcp

An MCP (Model Context Protocol) server that exposes NovelAI anime image generation (NAI Diffusion 5 by default, Diffusion 4.5 selectable) to LLM clients.

Built on top of the NovelAI.ImageGen .NET library.

Tool: generate_image

Generates an anime-style image using NovelAI. Specify categorized scene tags and optional characters with categorized appearance tags. Use booru-style tags (underscores, lowercase).

Parameters

Parameter	Type	Required	Default	Description
scene_tags	object	yes	—	Categorized scene tags: location, objects, composition (each a string array)
characters	array	no	[]	Characters with tags (identity, hair, face, body, clothing, accessories, pose), gender, and undesired_tags (per-character negatives)
model	string	no	"v5"	Model generation: v5 (Diffusion 5) or v4 (Diffusion 4.5). Unknown values fall back to v5.
transparent_background	bool	no	false	Request a transparent background (alpha). V5 only; ignored on V4.
aspect_ratio	string	no	"portrait"	portrait (832×1216), landscape (1216×832), square (1024×1024)
use_quality_tags	bool	no	true	Append internal quality tags to positive/negative prompts
seed	integer	no	random	Seed for reproducible generation
negative_tags	string[]	no	[]	Additional negative tags appended to quality negatives

Result

Returns a text content block with the saved file path and seed/dimensions, plus an image content block with the generated PNG.

Configuration

Set the NOVELAI_API_KEY environment variable:

export NOVELAI_API_KEY=your-key-here

Optional settings via appsettings.json or environment variables (NOVELAI_MCP_ prefix):

Setting	Default	Description
McpServer:OutputDirectory	_ImageGen	Where generated images are saved
McpServer:SavedPathPrefix	_ImageGen	Path prefix reported to the client
McpServer:TagDatabasePath	externals/booru_tag_db_dart/data/final/tag_database.db	Path to the booru tag database. If the file doesn't exist, tag browsing tools are silently disabled. The default path is relative — set an absolute path if launching from a different working directory.

Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "novelai-imagegen": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/src/NovelAI.ImageGen.Mcp"],
      "env": {
        "NOVELAI_API_KEY": "your-key-here"
      }
    }
  }
}

Other MCP Clients

The server communicates over stdio (JSON-RPC). Run it as a subprocess:

dotnet run --project src/NovelAI.ImageGen.Mcp

Building

git clone --recurse-submodules https://git.kagaku.eu/TeamAI/NovelAI.ImageGen.Mcp.git
cd NovelAI.ImageGen.Mcp
dotnet build
dotnet test

Architecture

externals/NovelAI.ImageGen/   ← git submodule (the client library)
src/NovelAI.ImageGen.Mcp/     ← MCP server (this project)
  Configuration/              ← options (API key, output dir)
  Prompts/                    ← tag flattening + quality tags
  Storage/                    ← image saving
  Tools/                      ← MCP tool definition + parameter DTOs
  Program.cs                  ← stdio host + DI wiring
tests/                        ← unit tests (NSubstitute + xUnit)

Quality Tags

The use_quality_tags flag (default: true) appends internally-defined quality tags:

Positive:

Tag	Strength
masterpiece	1.0
best quality	1.0
very aesthetic	1.0
absurdres	1.0
game cgi	1.0
monochrome	-1.0
year 2025	1.0
bad hands	-1.0
flat color	-1.0
bad anatomy	-1.0
simple illustration	-3.0

Negative:

Tag	Strength
lowres	1.0
worst quality	1.0
low quality	1.0
jpeg artifacts	1.0
very displeasing	1.0

Edit Prompts/QualityTags.cs to update.

License

MIT