NovelAI-Image-MCP

# NovelAI Image MCP

## Languages

| English | 简体中文 | 日本語 |
|---|---|---|
| [English](README.md) | [简体中文](.github/docs/README-zh.md) | [日本語](.github/docs/README-ja.md) |

[![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** to AI agents (Claude Desktop, Cline, custom agents, remote
clients), plus a sync CLI and three [skills.sh][skills-site] packages that teach
those agents how to drive either surface.

Built on FastMCP 4 (the fastmcp framework over the MCP SDK v2 `mcp>=2.3.0`),
it covers txt2img / img2img / inpaint, 4× upscale, Director tools (line art,
emotion, background removal, …), ControlNet annotation, tag suggestions, vibe
encoding and account subscription — all through the standard MCP tool
interface.

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

## Three ways to drive it

All three wrap the same async `NovelAIClient`; they differ in how you invoke
it.

- **MCP tools** — interactive agent sessions (Claude Desktop, Cline, …). The
  agent sees base64 `Image` content blocks.
- **CLI** — shell scripting, CI jobs, one-off commands. Saves a PNG and prints
  its path; no image blocks.
- **Agent skills** — portable instructions that tell an agent how to use the
  other two. They inherit the mode they drive.

## Features

- **11 MCP tools** covering the full NovelAI image API surface.
- **2 prompts + 3 resources + 1 resource template**: house-style prompt drafting and tool sequencing
  (`novelai_prompt_writer`, `novelai_image_workflow`), plus `novelai://models`,
  `novelai://samplers`, `novelai://defaults` and `novelai://outputs/{name}` for
  discovering the model/sampler vocabulary and reading generated PNGs back.
- **Three agent skills** (`novelai-cli`, `novelai-mcp-tools`,
  `novelai-workflows`) grouped as CLI / MCP Tools / Workflows, installable with
  one `npx skills add` command.
- **A sync `typer` CLI** with six subcommands for scripting outside an MCP host.
- **Two transports**: stdio (local agents) + HTTP (remote / multi-client), the
  latter optionally protected by a bearer token (`MCP_AUTH_TOKEN`).
- **Opt-in routing and audit (HTTP)**: a client that sends `X-MCP-Insiders`
  gets per-route output directories, per-route loggers and an append-only JSONL
  audit trail (prompts and credentials are never written verbatim). Without the
  header nothing changes. See
  [Insiders header, routing and audit][insiders-docs].
- **Structured results**: enum-validated tool schemas, MCP tool annotations and
  `ToolError` for expected failures.
- **Dual image return**: base64 `Image` content blocks (the agent *sees* the image)
  **and** PNG saved to disk (path returned as text).
- **Monorepo**: uv workspace (Python) + pnpm workspace (Node tooling) orchestrated
  by Turbo; MIT-licensed, Docker-ready, GitHub Pages docs.

## Quick start

### 1. Install the agent skills

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

`--yes` skips the interactive picker; `--global` installs to
`~/.agents/skills/` so every project on the machine can use them. Drop
`--global` to install into the current project's `.agents/skills/` instead.
See [Agent skills](#agent-skills) for what each skill covers.

### 2. Install the server (from source, development)

```bash
# 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=http uv run python -m novelai_image_mcp serve
#   → http://127.0.0.1:8000/mcp
```

### 3. Install the server (PyPI, runtime only)

```bash
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:

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

This wires the husky pre-commit + commit-msg hooks and gives you `turbo` /
`markdownlint-cli2` for local development. The MCP server has **zero** Node
runtime dependencies — this step is only for contributors.

## Connect an agent

The MCP server supports two transports (stdio + http), all configured under
`mcpServers`:

### stdio (local agent — Claude Desktop / Cline)

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "novelai-image": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/NovelAI-Image-MCP",
        "python",
        "-m",
        "novelai_image_mcp",
        "serve"
      ],
      "env": {
        "NOVELAI_TOKEN": "${input:novelai_token}"
      }
    }
  }
}
```

#### Alternative: uvx (published package)

```json
{
  "mcpServers": {
    "novelai-image": {
      "command": "uvx",
      "args": ["novelai-image-mcp", "serve"],
      "env": { "NOVELAI_TOKEN": "pst-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}
```

Set `NOVELAI_TOKEN` (or `NOVELAI_USERNAME` + `NOVELAI_PASSWORD`) in the host
environment before launching — `uvx` inherits the parent shell env.

### http (remote / Docker deployment)

After `docker compose up --build` (server listens on `http://HOST:8000/mcp`):

```json
{
  "mcpServers": {
    "novelai-image-http": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer pst-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Replace `http://127.0.0.1:8000/mcp` with your self-deployed endpoint (e.g.
`https://mcp.example.com/mcp` behind a TLS-terminating reverse proxy). Swap
the literal token placeholder for a host-managed secret reference if your
MCP host supports one (Claude Desktop, Cline, etc. expose this via their
own secrets UI).

### Standard FastMCP entry points

The repository ships a [`fastmcp.json`](fastmcp.json) whose source points at
`apps/server/mcp_server.py`, so plain FastMCP tooling works too (run from the
repository root, after `uv sync`):

```bash
uv run fastmcp run fastmcp.json                     # stdio server
uv run fastmcp inspect                              # list tools/prompts/resources
uv run --directory apps/server fastmcp dev inspector mcp_server.py   # Inspector
```

`fastmcp.json` has no `environment` block on purpose: the workspace virtualenv
already has the package installed, and an `environment` entry would make
FastMCP build a second, throwaway environment for every run.

## CLI (sync, for scripting)

The CLI exposes six subcommands: `serve`, `generate`, `upscale`, `director`,
`annotate`, `info`.

```bash
# Run the MCP server (stdio by default; -t http for the HTTP transport)
novelai-image-mcp serve

# Text-to-image — prints one absolute PNG path per generated image
novelai-image-mcp generate --prompt "a cat, masterpiece" --width 832 --height 1216

# 4x upscale (V5 model only)
novelai-image-mcp upscale --image ./in.png --factor 4

# Director tools: lineart | sketch | bg-removal | declutter | colorize | emotion
novelai-image-mcp director lineart ./photo.png --defry 5

# ControlNet annotation: hed | midas | fake_scribble | mlsd | uniformer
novelai-image-mcp annotate ./photo.png --model hed

# Subscription / Anlas balance
novelai-image-mcp info

novelai-image-mcp --help
```

Install it with `pip install novelai-image-mcp`, run it ad hoc with
`uvx novelai-image-mcp <command>`, or from the monorepo with
`uv run --directory apps/server novelai-image-mcp <command>`. Every
image-producing command saves a PNG to `NOVELAI_OUTPUT_DIR` (default
`outputs`) and prints its path; `-o` / `--output-dir` overrides the
directory for one invocation. The full flag list lives in the
[`novelai-cli` skill][skills-docs].

## Agent skills

Three [skills.sh][skills-site] packages ship in `skills/`. They teach AI
agents (Claude Code, Codex, GitHub Copilot, Cursor, …) how to drive the CLI and
the MCP tools, so you do not have to paste docs into the conversation.

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

```mermaid
graph TD
    Q{How will you drive NovelAI?}
    Q -->|"Interactive session with an MCP host"| MCP["MCP tools<br/>11 tools over stdio / http"]
    Q -->|"Shell script, CI job, one-off command"| CLI["CLI<br/>novelai-image-mcp generate ..."]
    Q -->|"Let an agent pick the right one"| SK["Agent skills<br/>novelai-cli / novelai-mcp-tools / novelai-workflows"]
    SK --> MCP
    SK --> CLI
```

| Skill | Group | What it teaches |
|---|---|---|
| `novelai-cli` | CLI | Typer CLI commands (serve, generate, upscale, director, annotate, info) for shell scripting |
| `novelai-mcp-tools` | MCP Tools | The 11 MCP tools — model selection, parameters, return shape, Anlas cost |
| `novelai-workflows` | Workflows | Multi-step creative pipelines (txt2img→upscale, annotate→img2img, Director edits) |

Skills and the CLI/MCP tools are complementary, not either/or: install all
three and the agent picks the mode that fits the task. Each skill points at the
other two instead of repeating them. See the [Agent skills docs][skills-docs]
for the group descriptions and a mode-comparison table.

## Repository layout

This is a **uv + pnpm monorepo**:

```text
NovelAI-Image-MCP/
├── apps/
│   ├── server/                 # MCP server (the installable PyPI package)
│   │   ├── src/novelai_image_mcp/   # 11