NovelAI Image MCP

NovelAI Image MCP

语言

English	简体中文	日本語
English	简体中文	日本語

一个 MCP（Model Context Protocol） 服务，可将 NovelAI 图像生成提供给 AI Agent（Claude Desktop、Cline、自定义 Agent、远程客户端）使用，还提供同步 CLI 和三个 skills.sh 软件包，指导这些 Agent 使用这两种方式。

该项目基于 FastMCP 4 构建（采用 MCP SDK v2 mcp>=2.3.0 的 fastmcp 框架），支持 txt2img / img2img / inpaint、4× 放大、Director 工具（线稿、情绪、背景移除等）、ControlNet 标注、标签建议、vibe 编码和账户订阅，全部通过标准 MCP 工具接口提供。

📖 文档：xinvxueyuan.github.io/NovelAI-Image-MCP

三种使用方式

三种方式均使用同一个异步 NovelAIClient，区别在于调用方式。

• MCP 工具——用于交互式 Agent 会话（Claude Desktop、Cline 等）。Agent 可查看 base64 Image 内容块。
• CLI——用于 shell 脚本、CI 任务和一次性命令。保存 PNG 并输出其路径；不提供图像块。
• Agent 技能——为 Agent 提供可移植的操作说明，指导其使用另外两种方式。技能采用其所驱动方式的运行模式。

功能特性

• 11 个 MCP 工具，涵盖完整的 NovelAI 图像 API。
• 2 个提示词 + 3 个资源 + 1 个资源模板：用于编写符合既定风格的提示词并排列工具调用顺序（novelai_prompt_writer、novelai_image_workflow），还提供 novelai://models、novelai://samplers、novelai://defaults 和 novelai://outputs/{name}，用于了解模型和采样器的词汇表，以及读取生成的 PNG。
• 三个 Agent 技能（novelai-cli、novelai-mcp-tools、novelai-workflows），归类为 CLI / MCP Tools / Workflows，可通过一条 npx skills add 命令安装。
• 同步 typer CLI，提供六个子命令，可在 MCP 主机之外编写脚本。
• 两种传输方式：stdio（本地 Agent）+ HTTP（远程 / 多客户端）；后者可选择使用 bearer token（MCP_AUTH_TOKEN）进行保护。
• 可选路由和审计（HTTP）：客户端发送 X-MCP-Insiders 后，将获得按路由划分的输出目录、按路由划分的日志记录器，以及仅追加的 JSONL 审计记录（不会原样写入提示词和凭据）。不发送此标头时，不会有任何变化。请参阅Insiders 标头、路由和审计。
• 结构化结果：经过枚举验证的工具架构、MCP 工具注释，以及用于预期故障的 ToolError。
• 双重图像返回：base64 Image 内容块（Agent 可查看图像）以及保存到磁盘的 PNG（以文本形式返回路径）。
• Monorepo：由 Turbo 编排的 uv 工作区（Python）+ pnpm 工作区（Node 工具链）；采用 MIT 许可证、支持 Docker，并提供 GitHub Pages 文档。

快速开始

1. 安装 Agent 技能

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

--yes 跳过交互式选择器；--global 将技能安装到 ~/.agents/skills/，以便本机上的所有项目都能使用。若要安装到当前项目的 .agents/skills/，请移除 --global。有关各技能的内容，请参阅 Agent 技能。

2. 安装服务（从源码安装，用于开发）

# 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. 安装服务（PyPI，仅运行时依赖）

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

可选：Node 工具链（贡献者）

如果你计划贡献代码，请通过 pnpm 安装通用 Node 工具链（turbo、 husky、markdownlint）：

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

这会配置 husky 的 pre-commit 和 commit-msg 钩子，并为本地开发提供 turbo / markdownlint-cli2。MCP 服务完全没有 Node 运行时依赖——此步骤仅供贡献者使用。

连接 Agent

MCP 服务支持两种传输方式（stdio + http），均在 mcpServers 下配置：

stdio（本地 Agent — Claude Desktop / Cline）

claude_desktop_config.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}"
      }
    }
  }
}

替代方案：uvx（已发布的软件包）

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

启动前，请在宿主环境中设置 NOVELAI_TOKEN（或 NOVELAI_USERNAME + NOVELAI_PASSWORD）——uvx 会继承父 Shell 环境变量。

http（远程 / Docker 部署）

运行 docker compose up --build 后（服务监听 http://HOST:8000/mcp）：

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

将 http://127.0.0.1:8000/mcp 替换为你自行部署的端点（例如，位于终止 TLS 的反向代理后面的 https://mcp.example.com/mcp）。如果你的 MCP 宿主支持机密引用（Claude Desktop、Cline 等通过各自的机密管理界面提供此功能），请将字面令牌占位符替换为由宿主管理的机密引用。

标准 FastMCP 入口点

仓库提供了一个 fastmcp.json，其源指向 apps/server/mcp_server.py，因此普通 FastMCP 工具也能正常工作（在仓库根目录运行，并先执行 uv sync）：

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 特意不包含 environment 块：工作区虚拟环境中已安装该软件包，而 environment 条目会导致 FastMCP 每次运行时都构建一个临时的第二环境。

CLI（同步，用于脚本编写）

CLI 提供六个子命令：serve、generate、upscale、director、 annotate、info。

# 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

可通过 pip install novelai-image-mcp 安装，使用 uvx novelai-image-mcp <command> 临时运行，或在 monorepo 中使用 uv run --directory apps/server novelai-image-mcp <command> 运行。每个生成图像的命令都会将 PNG 保存到 NOVELAI_OUTPUT_DIR（默认为 outputs）并打印其路径；-o / --output-dir 可为单次调用指定其他目录。完整的标志列表见 novelai-cli 技能。

Agent 技能

skills/ 中提供了三个 skills.sh 软件包。它们会指导 AI Agent（Claude Code、Codex、GitHub Copilot、Cursor 等）如何使用 CLI 和 MCP 工具，因此你无需将文档粘贴到对话中。

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

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

技能	分组	说明
novelai-cli	CLI	用于 Shell 脚本编写的 Typer CLI 命令（serve、generate、upscale、director、annotate、info）
novelai-mcp-tools	MCP 工具	11 个 MCP 工具——模型选择、参数、返回格式、Anlas 成本
novelai-workflows	工作流	多步骤创作流程（txt2img→upscale、annotate→img2img、Director 编辑）

技能与 CLI/MCP 工具相辅相成，并非二选一：全部安装后，Agent 会选择适合任务的模式。每项技能都会链接到其他两项，而不是重复介绍。有关分组说明和模式比较表，请参阅 Agent 技能文档。

仓库布局

这是一个 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
├── skills/                      # skills.sh packages (novelai-cli, ...)
├── skills.sh.json               # skill groupings for skills.sh
├── .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

开发者指南请参阅 CONTRIBUTING.md，完整文档源请参阅 apps/docs/source/。

工具

工具	描述
generate_image	文本生成图像（V3 / V4 / V4.5 / V5 模型、角色提示词；氛围仅支持 V4/V4.5）
image_to_image	图生图，可设置强度/噪声
inpaint	图像修复（需要修复模型和蒙版）
upscale_image	4× 放大（V5 模型）
director_tool	线稿 / 草图 / 背景移除 / 杂物清理 / 上色 / 表情
annotate_image	ControlNet 标注（hed、midas、scribble、mlsd、uniformer）
suggest_tags	提示词标签建议
encode_vibe	将参考图像编码为氛围令牌
get_subscription	账户订阅信息和 Anlas 余额
get_user_data	账户用户数据
estimate_anlas_cost	估算生成所需的 Anlas 费用（不调用 API）

请参阅文档站点上的工具参考， 了解参数和示例。

配置

所有设置均为环境变量（参见 .env.example）。主要设置如下：

变量	默认值	说明
NOVELAI_TOKEN	—	持久化 API 令牌（首选身份验证方式）
NOVELAI_USERNAME / NOVELAI_PASSWORD	—	使用访问密钥登录（argon2id）
NOVELAI_OUTPUT_DIR	outputs	保存生成 PNG 的位置
NOVELAI_DEFAULT_MODEL	nai-diffusion-4-5-full	工具调用未指定模型时使用的模型 ID
NOVELAI_DEFAULT_WIDTH / NOVELAI_DEFAULT_HEIGHT	832 / 1216	默认图像尺寸
NOVELAI_DEFAULT_STEPS	28	默认采样步数（1–50）
NOVELAI_DEFAULT_SCALE	5.0	默认 CFG 比例（≤20）
NOVELAI_DEFAULT_SAMPLER	k_euler_ancestral	默认采样器
NOVELAI_UPSCALE_MODEL	nai-diffusion-5-full	独立 4× 放大器使用的模型（仅限 V5 系列）
NOVELAI_TIMEOUT	120	HTTP 超时时间（秒）
NOVELAI_IMAGE_BASE_URL	https://image.novelai.net	用于生成和账户端点的统一 API 主机
NOVELAI_LEGACY_IMAGE_BASE_URL	https://api.novelai.net	主 API 主机；仅 /ai/annotate-image 仍使用此主机
MCP_TRANSPORT	stdio	stdio 或 http（streamable-http 是旧版别名）
MCP_HOST / MCP_PORT / MCP_PATH	127.0.0.1 / 8000 / /mcp	用于 HTTP 传输
MCP_AUTH_TOKEN	—	设置后，HTTP 传输需要 Authorization: Bearer <token>
MCP_ROUTE_TOKENS	—	JSON {"<route>": "<token>"} 路由绑定的不记名令牌（路由不匹配时返回 401）
MCP_INSIDERS_HEADER	X-MCP-Insiders	客户端选择加入时使用的标头（仅限 HTTP）
MCP_MODEL_HEADERS / MCP_AGENT_HEADERS / MCP_CLIENT_HEADERS	见下文	JSON 路由候选列表，使用第一个非空标头
MCP_INSIDERS_DISABLED_FEATURES	[]	运维方紧急停用开关（JSON 列表），优先于任何客户端设置
MCP_ROUTE_SCOPED_OUTPUT	true	路由启用期间，将图像写入 <output>/<route>/
MCP_AUDIT_LOG_PATH	<output>/audit.jsonl	仅追加的 JSONL 审计记录
MCP_LOG_LEVEL	—	DEBUG/INFO/WARNING/ERROR/CRITICAL

列表和字典类型的设置会按 JSON 读取：MCP_MODEL_HEADERS='["X-MCP-Model"]' 有效，而 A,B 会引发设置错误，空值也不是有效的 JSON。

路由候选默认值（JSON 列表，使用第一个非空标头）：

• MCP_MODEL_HEADERS — ["X-MCP-Model", "X-MCP-Model-Name"]
• MCP_AGENT_HEADERS — ["X-MCP-Agent-ID", "X-MCP-Agent", "X-MCP-Agent-Source"]
• MCP_CLIENT_HEADERS — ["X-MCP-Client", "X-MCP-Client-Session-Id"]

Insiders 标头与路由

通过 HTTP，客户端可以选择启用实验性行为，并声明请求所属的路由、 模型、Agent 和会话：

X-MCP-Insiders: true
X-MCP-Agent-ID: team-a
X-MCP-Model: nai-diffusion-5-full

随后，服务端会将该请求的图像写入 <NOVELAI_OUTPUT_DIR>/team-a/，向 novelai_image_mcp.audit.team-a 日志记录器写入一行，并向审计 JSONL 追加一条记录（该记录保留提示词的长度和截断后的 SHA-256，不会保存 提示词，也不会保存凭据标头或图像负载）。

没有标头时不会有任何变化——不会创建作用域目录或审计文件，也不会添加或移除 工具——但有一个特意设置的例外：director_tool 的 emotion 和 emotion_level 参数现在需要启用选项，否则会返回 ToolError（参见 CHANGELOG）。 路由标头由客户端提供且可以伪造，因此只能在受信任的网关后授予启用选项。

完整约定：Insiders 标头、路由与审计。

NovelAI API 参考：image.novelai.net/docs

开发

该项目是由 Turbo 编排的 uv + pnpm monorepo。完整设置说明请参见 CONTRIBUTING.md；简要步骤如下：

uv sync                              # Python workspace (server + docs + dev)
pnpm install --frozen-lockfile       # Node toolchain (turbo + husky + markdownlint)

pnpm check                           # lint + typecheck + test (all workspaces)
pnpm docs:build                       # build the docs site
pnpm server:serve                     # run the MCP server
pnpm docs:serve                       # sphinx-autobuild with live reload

各成员的命令（通过 uv）：

uv run --directory apps/server ruff check src tests    # lint
uv run --directory apps/server -m pyright              # typecheck
uv run --directory apps/server -m pytest               # tests

Docker

docker compose up --build      # builds and runs the server (HTTP transport)

Dockerfile 位于 apps/server/Dockerfile，但 构建上下文是仓库根目录（这样 uv 才能解析工作区依赖图）。请参见 docker-compose.yml。

文档

Sphinx 文档站点使用 Furo + MyST Markdown 构建，并会在每次推送到 main 时 自动部署到 GitHub Pages：

• 在线站点：xinvxueyuan.github.io/NovelAI-Image-MCP
• 源文件：apps/docs/source/
• 本地构建：pnpm docs:serve

许可证

MIT——详见 LICENSE。各文件的 SPDX 注释位于 REUSE.toml。贡献须遵守 开发者原创证书（commit-msg 钩子会自动为提交添加签署声明）。

Links