nai-mcp — NovelAI 生图API MCP Server

独立的 stdio MCP Server，可接入 Claude Code / Codex / Cline 等任何支持 MCP 的 agent。请求格式对齐官方 OpenAPI 文档（image.novelai.net/docs）。生图始终走"命名工作流"：set 类工具只填参数不花钱，确认后再出图。

快速开始

cd nai_mcp
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt
# 可选：构建 tag 词库（自动从 GitHub 下载 Launcher 发布的 tag_catalog.db）
.venv/Scripts/python tool/build_tag_vector_db.py --db tag_vectors.db --with-ffdkj

在客户端注册 stdio server，token 走环境变量：

{
  "mcpServers": {
    "nai-mcp": {
      "command": "C:/Users/你的用户名/codes/nai_mcp/.venv/Scripts/python.exe",
      "args": ["C:/Users/你的用户名/codes/nai_mcp/server.py"],
      "env": { "NAI_TOKEN": "pst-你的持久令牌" }
    }
  }
}

NAI_TOKEN：NovelAI 持久令牌（pst- 开头，账户设置 → API 令牌创建），或短期用户访问令牌。

Agent 全局约定（已写入 server instructions）：默认模型为 nai-diffusion-5-full；出图默认以 0 Anlas（Opus 免费档：steps ≤ 28、≤ 1024×1024）为目标；写提示词前先用 search_tag 规范化，角色/主体优先用 category=character 的角色 tag。

Related MCP server: NovelAI Image MCP

工具一览

工作流存储为 nai_mcp/workflows/<name>.json（env NAI_MCP_WORKFLOW_DIR 可改目录）。set 类工具只做部分更新，可任意顺序组合再生成。

模型与采样预设

支持模型（默认加粗）：nai-diffusion-5-full、nai-diffusion-5-curated、nai-diffusion-5-full-medium、nai-diffusion-4-5-full、nai-diffusion-4-5-curated、nai-diffusion-4-full、nai-diffusion-3

• 预设（来自 Launcher ModelCapabilities）：步数 28（V5 Medium 固定 14）；引导系数 V5 4.0 / V4.5 5.0 / V4 5.5 / V3 5.0；采样器 k_euler_ancestral；噪声调度 karras；UC 预设 heavy；img2img strength 0.7 / noise 0.0

• V5 特有：UC light 为 V5 专属文案；nai-diffusion-5-full-medium 不发送 cfg_rescale；Anlas 模型倍率 1.5，且 Opus 免费额度改为官方配额池（见下文计费节；估价文本自动提示）

• 官方质量词与 UC 预设文本自动补全；DDIM 仅 V3（V4+ 按官网规则回退 Euler Ancestral）

• UC 约定：预设（heavy/light/humanFocus/none）已自带整套官方质量负面词（lowres、worst quality 等）。自定义 uc 只需写想规避的特定缺陷/构图目标词，别重复质量词以免权重被放大

Inpaint（局部重绘）

工作流同时有底图 + 蒙版时，generate_image 自动按官网 infill 规则出图：

• 模型自动切到 inpainting 变体（如 nai-diffusion-4-5-full → …-inpainting；V5 Curated 官方映射到 V4.5 Curated Inpainting），请求带 mask 分块，extra_noise_seed = seed - 1

• 蒙版二选一：rects（server 自行渲染归一化矩形，agent 无需图像编辑能力）或 mask_path（PNG 白=重绘，自动二值化 + 缩放）

• 蒙版 strength 默认 1.0（Launcher inpaintStrength）；<1 时按官网规则附带 img2img 复用原图潜空间。底图 strength（默认 0.7）控制整体变化强度，两者独立

• Enhance 与蒙版互斥（增强是全图重绘），设置蒙版时调用会明确报错

计费与 Anlas 估价

移植 Launcher AnlasCalculator（现代模型公式）。估价工具自动查询订阅档位（GET /user/subscription），文本均标注"服务端计费为准"：

• 文生图：Opus 且 steps ≤ 28、≤ 1024×1024 时首张免费

• 云端超分：Opus 输入 ≤ 640×640 免费，否则按输入面积 1-4 Anlas 分档

• 订阅查询失败按非 Opus 估算并注明

V5 配额用量查看（read_workflow / estimate_anlas）

V5 的 Opus 免费额度是配额池而非无条件免费：随时间自动回充、额度与图面积挂钩（官网口径 1% ≈ 17.3 张 ≤1MP 免费图；大图按 2/3/4 份/张折算），透支后 V5 按正常价扣 Anlas。估价文本附加实时用量行（对齐 Launcher OpusUsageChip）：

• 正常：V5 配额：剩余 97.3%，约可免费生成 1683 张 1MP 图（…配额随时间自动回充…）

• 透支：V5 配额：已透支（V5 生成将按正常价扣 Anlas；配额随时间自动回充，达标后恢复免费）

• 数据源：/user/subscription 的 usage 字段（percent / isNegative / timeUntilNextPercent）；回充超过 100% 保留真实值；非 Opus 或查询失败时不附加

tag 词库与语义检索

词库由 tool/build_tag_vector_db.py 生成（优先级同 Launcher：手工修订中文 > ffdkj 全量中文）：

• tag_catalog.db：tag 名单、别名（37,790 条）与手工修订中文。默认自动获取：读 Launcher 仓库 main 分支的 assets/databases/manifest.json，下载其官方 release 资产并按清单锁定 SHA-256/大小校验，缓存在 tool/.tmp/tag_catalog.db（该文件在仓库内是 LFS，单纯 raw 下载会拿到 pointer，故走 release）。--source <路径> 可跳过网络用本地文件

• ffdkj 中文翻译表（--with-ffdkj，推荐）：全量 32 万条中文。按 Launcher zh_dictionary_download.dart 锁定的 URL 下载、按固定 SHA-256 校验，缓存为 tool/.tmp/ffdkj_tag.sqlite

server 通过 env NAI_TAG_DB 指词库（默认项目根 tag_vectors.db）。

# 生成词库
.venv/Scripts/python tool/build_tag_vector_db.py --db tag_vectors.db --with-ffdkj

# 填充 embeddings（启用语义检索；不带参数默认填全部未填充行，可分批）
$env:NAI_EMBEDDING_URL = "https://你的-embeddings-端点"
$env:NAI_EMBEDDING_MODEL = "text-embedding-xxx"
$env:NAI_EMBEDDING_API_KEY = "..."   # 可选
.venv/Scripts/python tool/fill_tag_vectors.py

fill_tag_vectors.py 性能：请求打满模型 token 上限 + 并发。默认按 32k 输入模型：NAI_EMBED_BATCH_TOKENS=24000、NAI_EMBED_CHARS_PER_TOKEN=1.0、NAI_EMBED_CONCURRENCY=4；脚本参数 --min-post-count / --max-rows 可先填高频 tag；429/5xx 指数退避，响应带 index 时按 index 回填。参考量级：22 万行 ≈ 200 个请求、4 并发几十分钟。tool/mock_embeddings_server.py 可离线验证链路。

词向量填充前，search_tag 为中文/别名/词面检索（约 0.1s）；配置 embeddings 后自动启用余弦语义（如"面向观众" → looking at viewer，向量 numpy float32 矩阵单次乘，查询耗时主要是 embeddings 网络延迟 1-4s）。未装 numpy 自动回退纯 Python。

环境变量

验证

.venv/Scripts/python smoke_test.py — 全离线：stdio 握手、14 个工具、工作流创建/读写、Anlas 估价与 V5 配额格式化、角色/底图/蒙版设置、tag 检索、错误路径（不触网、不扣费）。

参考实现：Aaalice_NAI_Launcher

本项目大量实现取自参考项目 Aaalice233/Aaalice_NAI_Launcher（Flutter 桌面客户端），按其内部实现的公开行为移植并复刻口径：

• Anlas 计费公式与 Opus 免费判断 —— AnlasCalculator 现代公式、云端超分分档

• 模型采样预设、UC 质量词/预设文本、inpainting 变体映射 —— ModelCapabilities / ImageModels

• V5 Opus 配额池口径与展示（1% ≈ 17.3 张、透支语义、回充） —— OpusUsageInfo / /user/subscription 解析 / OpusUsageChip

• tag 词库与中文翻译来源、锁定哈希校验 —— tool/tag_catalog/ 与 zh_dictionary_download.dart