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.
Transports: stdio (local agents) + streamable-http (remote / multi-client).
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=streamable-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.

Development Status
- 3 - Alpha
Environment
- Console
Framework
- AsyncIO
Intended Audience
- Developers
Natural Language
- English
Operating System
- OS Independent
Programming Language
Topic
- Multimedia :: Graphics
- Scientific/Engineering :: Artificial Intelligence

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

novelai_image_mcp-0.4.0.tar.gz (40.2 kB view details)

Uploaded Aug 28, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

novelai_image_mcp-0.4.0-py3-none-any.whl (48.0 kB view details)

Uploaded Aug 28, 2026 Python 3

File details

Details for the file novelai_image_mcp-0.4.0.tar.gz.

File metadata

Download URL: novelai_image_mcp-0.4.0.tar.gz
Upload date: Aug 28, 2026
Size: 40.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for novelai_image_mcp-0.4.0.tar.gz
Algorithm	Hash digest
SHA256	`e71319af528449428c26a32fa4c2593a90064f0ca003e574b599a10af6319a37`
MD5	`a47a854e7dc895c9a8c171fbd6819550`
BLAKE2b-256	`6097f85099ba3d0d85da9b68b3536faacc038fb3f63e61553c1f994ef3537d7d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for novelai_image_mcp-0.4.0.tar.gz:

Publisher: release.yml on xinvxueyuan/NovelAI-Image-MCP

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: novelai_image_mcp-0.4.0.tar.gz
- Subject digest: e71319af528449428c26a32fa4c2593a90064f0ca003e574b599a10af6319a37
- Sigstore transparency entry: 2626561126
- Sigstore integration time: Aug 28, 2026
Source repository:
- Permalink: xinvxueyuan/NovelAI-Image-MCP@aa741854c1eaf4fe971498f57db8b08210bf99b3
- Branch / Tag: refs/heads/releases/0.4.0
- Owner: https://github.com/xinvxueyuan
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@aa741854c1eaf4fe971498f57db8b08210bf99b3
- Trigger Event: push