NovelAI Image MCP server

NovelAI Image MCP

[![CI][ci-badge]][ci-workflow] [![Docs][docs-badge]][docs] [![License: MIT][mit-badge]][license] [![Python 3.13+][python-badge]][python] [![uv][uv-badge]][uv] [![REUSE status][reuse-badge]][reuse] [![DeepWiki][deepwiki-badge]][deepwiki] [![skills.sh][skills-badge]][skills-sh]

[![NovelAI Image MCP - MCP server for integrating NovelAI Image generation into AI | Product Hunt][product-hunt-badge]][product-hunt] [![Featured on Lifto][lifto-badge]][lifto]

An [MCP (Model Context Protocol)][mcp] 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.

📖 Documentation: [xinvxueyuan.github.io/NovelAI-Image-MCP][docs]

Features

and PNG saved to disk (path returned as text).

• 11 MCP tools covering the full NovelAI image API surface.
• Two transports: stdio (local agents) + streamable-http (remote / multi-client).
• Dual image return: base64 Image content blocks (the agent sees the image)

by Turbo; MIT-licensed, Docker-ready, GitHub Pages docs.

• Async + sync: async tool handlers + a typer CLI for direct invocation.
• Monorepo: uv workspace (Python) + pnpm workspace (Node tooling) orchestrated

Repository layout

This is a uv + pnpm monorepo:

NovelAI-Image-MCP/
├── apps/
│   ├── server/                 # MCP server (the installable PyPI package)
│   │   ├── src/novelai_image_mcp/   # 11 MCP tools + NovelAI HTTP client
│   │   ├── tests/
│   │   ├── docker/              # smoke-test entrypoint
│   │   ├── Dockerfile           # built with repo root as context
│   │   └── pyproject.toml       # ruff / pyright / pytest config
│   └── docs/                    # Sphinx documentation site
│       ├── source/              # MyST Markdown + conf.py
│       ├── Makefile
│       └── pyproject.toml
├── .github/                     # workflows, CODEOWNERS, issue templates
├── pyproject.toml               # uv workspace root (virtual)
├── uv.lock                      # single shared lockfile
├── pnpm-workspace.yaml          # pnpm workspace declaration
├── pnpm-lock.yaml               # Node toolchain lockfile
├── turbo.json                   # cross-workspace task graph
├── package.json                 # root scripts + dev toolchain
└── docker-compose.yml           # local container orchestration

See [CONTRIBUTING.md][contributing] for the developer guide and [apps/docs/source/][docs-source] for the full documentation source.

Quick start

Install from source (development)

# 1. Clone
git clone https://github.com/xinvxueyuan/NovelAI-Image-MCP.git
cd NovelAI-Image-MCP

# 2. Sync the uv workspace (installs server + docs + dev tools)
uv sync

# 3. Configure credentials
cp .env.example .env
#   set NOVELAI_TOKEN=...  (preferred)
#   or  NOVELAI_USERNAME + NOVELAI_PASSWORD

# 4. Run (stdio — for local agents)
uv run python -m novelai_image_mcp serve

# 5. Or over HTTP
MCP_TRANSPORT=streamable-http uv run python -m novelai_image_mcp serve
#   → http://127.0.0.1:8000/mcp

Install from PyPI (runtime only)

pip install novelai-image-mcp
export NOVELAI_TOKEN=pst-...
novelai-image-mcp serve

Optional: Node tooling (contributors)

If you plan to contribute, install the cross-cutting Node toolchain (turbo, husky, markdownlint) via pnpm:

corepack enable pnpm      # one-time
pnpm install --frozen-lockfile

Shortened. The full README is on GitHub.