内容
# 小说AI图像MCP
[](https://github.com/xinvxueyuan/NovelAI-Image-MCP/actions/workflows/ci.yml)
[](https://xinvxueyuan.github.io/NovelAI-Image-MCP/)
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://docs.astral.sh/uv/)
[](https://api.reuse.software/info/github.com/xinvxueyuan/NovelAI-Image-MCP)
[](https://deepwiki.com/xinvxueyuan/NovelAI-Image-MCP)
<a href="https://www.producthunt.com/products/novelai-image-mcp?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-novelai-image-mcp" target="_blank" rel="noopener noreferrer"><img alt="NovelAI Image MCP - MCP server for integrating NovelAI Image generation into AI | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1206099&theme=light&t=1784973837616"></a>
一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io/) 服务器，
暴露 **NovelAI图像生成** 作为AI代理（Claude Desktop，Cline，自定义代理，远程客户端）的工具。
基于官方MCP Python SDK v2（`MCPServer`），它允许代理生成图像（txt2img / img2img / inpaint），
放大图像，运行Director工具（线条艺术，情感，背景移除等），
用ControlNet注释，提示标签，建议编码，
查询账户订阅 - 所有这些都通过标准的MCP工具接口。
> 📖 **文档**: <https://xinvxueyuan.github.io/NovelAI-Image-MCP/>
## 功能
- **11个MCP工具**，涵盖完整的NovelAI图像API表面。
- **两种传输方式**：stdio（本地代理）+ streamable-http（远程/多客户端）。
- **双图像返回**：base64 `Image`内容块（代理*看到*图像）
**和** 保存到磁盘的PNG（路径作为文本返回）。
- **异步+同步**：异步工具处理程序 + `typer` CLI直接调用。
- **单体仓库**：uv工作区（Python）+ pnpm工作区（Node工具）由Turbo编排；
MIT许可，Docker就绪，GitHub Pages文档。
## 仓库布局
这是一个 **uv + pnpm单体仓库**：
```text
NovelAI-Image-MCP/
├── apps/
│ ├── server/ # MCP服务器（可安装的PyPI包）
│ │ ├── src/novelai_image_mcp/ # 11个MCP工具 + NovelAI HTTP客户端
│ │ ├── tests/
│ │ ├── docker/ # 烟雾测试入口
│ │ ├── Dockerfile # 使用仓库根目录作为上下文构建
│ │ └── pyproject.toml # ruff / pyright / pytest配置
│ └── docs/ # Sphinx文档站点
│ ├── source/ # MyST Markdown + conf.py
│ ├── Makefile
│ └── pyproject.toml
├── .github/ # 工作流程，CODEOWNERS，问题模板
├── pyproject.toml # uv工作区根目录（虚拟）
├── uv.lock # 单个共享锁定文件
├── pnpm-workspace.yaml # pnpm工作区声明
├── pnpm-lock.yaml # Node工具链锁定文件
├── turbo.json # 跨工作区任务图
├── package.json # 根目录脚本 + 开发工具链
└── docker-compose.yml # 本地容器编排
```
参见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 了解开发者指南，
[`apps/docs/source/`](apps/docs/source/) 了解完整的文档源。
## 快速开始
### 从源代码安装（开发）
```bash
# 1. 克隆
git clone https://github.com/xinvxueyuan/NovelAI-Image-MCP.git
cd NovelAI-Image-MCP
# 2. 同步uv工作区（安装服务器 + 文档 + 开发工具）
uv sync
# 3. 配置凭证
cp .env.example .env
# 设置 NOVELAI_TOKEN=... （首选）
# 或 NOVELAI_USERNAME + NOVELAI_PASSWORD
# 4. 运行（stdio — 用于本地代理）
uv run python -m novelai_image_mcp serve
# 5. 或通过HTTP
MCP_TRANSPORT=streamable-http uv run python -m novelai_image_mcp serve
# → http://127.0.0.1:8000/mcp
```
### 从PyPI安装（仅运行时）
```bash
pip install novelai-image-mcp
export NOVELAI_TOKEN=pst-...
novelai-image-mcp serve
```
### 可选：Node工具链（贡献者）
如果您计划贡献，请通过pnpm安装跨领域的Node工具链（turbo，
husky，markdownlint）：
```bash
corepack enable pnpm # 一次性
pnpm install --frozen-lockfile
```
这将连接husky预提交 + 提交消息钩子，并为您提供 `turbo` /
`markdownlint-cli2` 用于本地开发。MCP服务器具有 **零** Node
运行时依赖项 - 此步骤仅适用于贡献者。
## 连接代理
MCP服务器支持两种传输方式（stdio + http），均在
`mcpServers` 下配置：
### stdio（本地代理 — 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}"
}
}
}
}
```
#### 替代方案：uvx（已发布的包）
```json
{
"mcpServers": {
"novelai-image": {
"command": "uvx",
"args": ["--prerelease=allow", "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`）：
```json
{
"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` 替换为您的自部署端点（例如，
`https://mcp.example.com/mcp` 在TLS终止反向代理后面）。如果您的
MCP主机支持，请将字面令牌占位符替换为主机管理的秘密引用。
## CLI（同步，用于脚本）
```bash
uv run python -m novelai_image_mcp generate --prompt "a cat, masterpiece" --width 832 --height 1216
uv run python -m novelai_image_mcp upscale --image ./in.png --factor 4
uv run python -m novelai_image_mcp info # 订阅 / Anlas余额
uv run python -m novelai_image_mcp --help
```
## 工具
| 工具 | 描述 |
|---|---|
| `generate_image` | 文本到图像（V3 / V4 / V4.5模型，角色提示，氛围） |
| `image_to_image` | 图像到图像，具有强度/噪声 |
| `inpaint` | 修复（需要修复模型 + 掩模） |
| `upscale_image` | 2倍 / 4倍放大 |
| `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调用） |
参见文档站点上的 [工具参考](https://xinvxueyuan.github.io/NovelAI-Image-MCP/tools/index.html)
以获取参数和示例。
## 配置
所有设置都是环境变量（参见 `.env.example`）。主要设置：
| 变量 | 默认值 | 备注 |
|---|---|---|
| `NOVELAI_TOKEN` | — | 持久API令牌（首选认证） |
| `NOVELAI_USERNAME` / `NOVELAI_PASSWORD` | — | 访问密钥登录（argon2id） |
| `NOVELAI_OUTPUT_DIR` | `outputs` | 生成的PNG保存位置 |
| `MCP_TRANSPORT` | `stdio` | `stdio` 或 `streamable-http` |
| `MCP_HOST` / `MCP_PORT` | `127.0.0.1` / `8000` | 用于streamable-http |
NovelAI API参考： <https://image.novelai.net/docs/index.html>
## 开发
该项目是一个由Turbo编排的uv + pnpm单体仓库。参见
[`CONTRIBUTING.md`](CONTRIBUTING.md) 了解完整设置；简要说明：
```bash
uv sync # Python工作区（服务器 + 文档 + 开发）
pnpm install --frozen-lockfile # Node工具链（turbo + husky + markdownlint）
pnpm check # 校验 + 类型检查 + 测试（所有工作区）
pnpm docs:build # 构建文档站点
pnpm server:serve # 运行MCP服务器
pnpm docs:serve # sphinx-autobuild，实时重载
```
每个成员的命令（通过uv）：
```bash
uv run --directory apps/server ruff check src tests # 校验
uv run --directory apps/server -m pyright # 类型检查
uv run --directory apps/server -m pytest # 测试
```
### Docker
```bash
docker compose up --build # 构建并运行服务器（HTTP传输）
```
Dockerfile位于 [`apps/server/Dockerfile`](apps/server/Dockerfile)，但
构建上下文是仓库根目录（因此uv可以解析工作区图）。参见 [`docker-compose.yml`](docker-compose.yml)。
## 文档
Sphinx文档站点使用Furo + MyST Markdown构建，
并在每次推送到 `main` 时自动部署到GitHub Pages：
- **实时站点**: <https://xinvxueyuan.github.io/NovelAI-Image-MCP/>
- **源代码**: [`apps/docs/source/`](apps/docs/source/)
- **本地构建**: `pnpm docs:serve`
## 许可证
MIT — 参见 [LICENSE](LICENSE)。每个文件的SPDX注释位于
[REUSE.toml](REUSE.toml)。贡献受
[开发者证书起源](https://developercertificate.org/) （
`commit-msg` 钩子自动签署提交）。
