# NovelAI Image MCP

> NovelAI Image MCP is an open-source MCP server for design and media. Generate and edit NovelAI images from an AI agent: txt2img, inpaint, upscale, ControlNet. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Website:** https://xinvxueyuan.github.io/NovelAI-Image-MCP/
- **Repository:** https://github.com/xinvxueyuan/novelai-image-mcp
- **MCP Registry name:** io.github.xinvxueyuan/novelai-image-mcp
- **Categories:** design and media
- **Listing updated:** 2026-11-14

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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.

## 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

- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [ffmpeg-skill](https://ai-powered.com/mcp/ffmpeg-skill): ffmpeg-skill is an open-source MCP server for design and media.
- [AvatarSay — Fictional Character & Talking Video MCP](https://ai-powered.com/mcp/avatarsay-fictional-character-and-talking-video-mcp): AvatarSay — Fictional Character & Talking Video MCP is a freemium MCP server for design and media.
- [ChartAnt](https://ai-powered.com/mcp/chartant): ChartAnt is a freemium MCP server for design and media.
- [VfxSmith](https://ai-powered.com/mcp/vfxsmith): VfxSmith is a freemium MCP server for design and media.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.
- [Eikino](https://ai-powered.com/mcp/eikino): Eikino is a freemium MCP server for security.
- [Hourlore](https://ai-powered.com/mcp/hourlore): Hourlore is a freemium MCP server for design and media.

---
Source: https://ai-powered.com/mcp/novelai-image-mcp
