NovelAI Image MCP

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 FastMCP 4 (the fastmcp framework over the MCP SDK v2 mcp>=2.0.0), 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.

This package is the server workspace member of the NovelAI-Image-MCP monorepo. The Sphinx documentation site lives at apps/docs/. See the repository root README for the project overview and the docs site for full guides and API reference.

Features

• 11 MCP tools covering the full NovelAI image API surface.
• 2 prompts + 3 resources: prompt templates for drafting and tool sequencing, plus novelai://models, novelai://samplers, novelai://defaults and novelai://outputs/{name}.
• Transports: stdio (local agents) + HTTP (remote / multi-client), the latter optionally protected by MCP_AUTH_TOKEN.
• 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.

Install

pip install novelai-image-mcp

Quick start

# 1. Configure credentials
export NOVELAI_TOKEN=pst-...   # from https://novelai.net > Account

# 2. Run (stdio — for local agents)
novelai-image-mcp serve

# 3. Or over HTTP
MCP_TRANSPORT=http novelai-image-mcp serve
#   → http://127.0.0.1:8000/mcp

Agent skills

Three skills.sh packages (novelai-cli, novelai-mcp-tools, novelai-workflows) teach AI agents how to drive the CLI and MCP tools:

npx skills add --yes --global xinvxueyuan/NovelAI-Image-MCP

License

MIT — see LICENSE. Per-file SPDX annotations live in REUSE.toml.