NovelAI Image MCP

NovelAI Image MCP

言語

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

[AIエージェント（Claude Desktop、Cline、カスタムエージェント、リモートクライアント）にNovelAI画像生成を提供するMCP（Model Context Protocol） サーバー]mcpです。同期CLIと、エージェントにどちらのインターフェースの使い方も教える3つのskills.shパッケージも備えています。

FastMCP 4（MCP SDK v2 mcp>=2.3.0 上に構築された fastmcp フレームワーク）を基盤とし、txt2img／img2img／inpaint、4×アップスケール、Director ツール（線画、感情、背景除去など）、ControlNet アノテーション、タグ候補の提案、vibe エンコーディング、アカウントのサブスクリプション情報を、標準の MCP ツールインターフェースを通じて利用できます。

📖 ドキュメント：xinvxueyuan.github.io/NovelAI-Image-MCP

3つの利用方法

どの方法も同じ非同期 NovelAIClient を使用します。違いは呼び出し方です。

• MCP ツール — エージェントとの対話型セッション（Claude Desktop、Cline など）。エージェントは base64 の Image コンテンツブロックを受け取ります。
• CLI — シェルスクリプト、CI ジョブ、単発コマンドに適しています。PNG を保存してパスを出力し、画像ブロックは使用しません。
• エージェントスキル — ほかの2つの利用方法をエージェントに教える、移植可能な手順です。利用する方法のモードを引き継ぎます。

機能

• 11個の MCP ツールで NovelAI 画像 API の全機能を網羅しています。
• 2つのプロンプト＋3つのリソース＋1つのリソーステンプレート：スタイルに沿ったプロンプトの作成とツールの実行順序（novelai_prompt_writer、novelai_image_workflow）に加え、モデル／サンプラーの用語を確認し、生成した PNG を読み戻すための novelai://models、novelai://samplers、novelai://defaults、novelai://outputs/{name} を提供します。
• 3つのエージェントスキル（novelai-cli、novelai-mcp-tools、novelai-workflows）を CLI／MCP Tools／Workflows に分類しており、npx skills add コマンド1つでインストールできます。
• MCP ホスト外でのスクリプト作成に使える、6つのサブコマンドを備えた同期 typer CLI。
• 2種類のトランスポート：stdio（ローカルエージェント）と HTTP（リモート／複数クライアント）。HTTP はベアラートークン（MCP_AUTH_TOKEN）で保護することもできます。
• オプトインのルーティングと監査（HTTP）：X-MCP-Insiders を送信するクライアントには、ルートごとの出力ディレクトリ、ルートごとのロガー、追記専用の JSONL 監査ログが適用されます（プロンプトや認証情報がそのまま記録されることはありません）。このヘッダーがない場合、動作は変わりません。詳しくはInsiders ヘッダー、ルーティング、監査をご覧ください。
• 構造化された結果：列挙型で検証されるツールスキーマ、MCP ツールアノテーション、想定内の失敗に対する ToolError。
• 画像の二重返却：base64 の Image コンテンツブロック（エージェントが画像を確認できます）と、ディスクに保存された PNG（パスをテキストで返します）。
• モノレポ：Turbo でオーケストレーションされた uv ワークスペース（Python）＋ pnpm ワークスペース（Node ツール）。MIT ライセンス、Docker 対応、GitHub Pages のドキュメント。

クイックスタート

1. エージェントスキルをインストールする

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

--yes は対話型の選択画面を省略します。--global は ~/.agents/skills/ にインストールし、マシン上のすべてのプロジェクトで利用できるようにします。--global を外すと、代わりに現在のプロジェクトの .agents/skills/ にインストールされます。各スキルの内容についてはエージェントスキルをご覧ください。

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 の実行時依存関係が一切ありません。この手順はコントリビューター専用です。

エージェントを接続する

MCP サーバーは 2 種類のトランスポート（stdio と http）に対応しており、すべて mcpServers の下で設定します。

stdio（ローカルエージェント — 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 は親シェルの環境変数を引き継ぎます。

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 などでは、それぞれのシークレット UI から設定できます）。

FastMCP の標準エントリーポイント

リポジトリには、ソースが apps/server/mcp_server.py を指す fastmcp.json が含まれているため、通常の 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 には 6 つのサブコマンドがあります：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> で一時的に実行するか、モノレポから uv run --directory apps/server novelai-image-mcp <command> で実行してください。画像を生成するコマンドはすべて、PNG を NOVELAI_OUTPUT_DIR（デフォルトは outputs）に保存し、そのパスを出力します。-o／--output-dir を指定すると、その実行に限り保存先ディレクトリを変更できます。すべてのフラグの一覧は novelai-cli スキルを参照してください。

エージェントスキル

3 つの skills.sh パッケージが skills/ に含まれています。AI エージェント（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	シェルスクリプトで使う Typer CLI コマンド（serve、generate、upscale、director、annotate、info）
novelai-mcp-tools	MCP Tools	11 個の MCP ツール — モデル選択、パラメーター、戻り値の形式、Anlas のコスト
novelai-workflows	Workflows	複数ステップのクリエイティブパイプライン（txt2img→upscale、annotate→img2img、Director による編集）

スキルと CLI／MCP ツールは相互に補完するものであり、どちらか一方を選ぶものではありません。3 つすべてをインストールすると、エージェントがタスクに適したモードを選択します。各スキルは内容を繰り返す代わりに、ほかの 2 つを参照します。グループの説明とモード比較表については、エージェントスキルのドキュメントを参照してください。

リポジトリの構成

これは uv + pnpm のモノレポです。

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 のみで使用可能な Vibe）
image_to_image	強度／ノイズを指定して画像から画像を生成
inpaint	インペインティング（インペイントモデルとマスクが必要）
upscale_image	4× アップスケール（V5 モデル）
director_tool	線画／スケッチ／背景除去／不要物除去／カラー化／感情
annotate_image	ControlNet アノテーション（hed、midas、scribble、mlsd、uniformer）
suggest_tags	プロンプトタグの候補を提案
encode_vibe	参照画像を 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 経由では、クライアントは実験的な動作を有効にし、リクエストがどのルート、 モデル、エージェント、セッションに属するかを指定できます。

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 ロガーに1行を出力し、監査用 JSONL に 1レコードを追加します（レコードにはプロンプトの長さと切り詰めた SHA-256 が記録されますが、 プロンプトそのもの、認証情報ヘッダー、画像データは記録されません）。

ヘッダーがなければ何も変わりません――スコープ付きディレクトリも監査ファイルも、 ツールの追加や削除もありません――ただし、意図的に設けた例外が1つあります。 director_tool の emotion と emotion_level パラメーターはオプトインが必須となり、 オプトインがなければ ToolError が発生します（CHANGELOG を参照）。 ルーティングヘッダーはクライアントが指定でき、偽装も可能なため、信頼できるゲートウェイの 背後でのみオプトインを許可してください。

仕様の全文：Insiders ヘッダー、ルーティング、監査。

NovelAI API リファレンス：image.novelai.net/docs

開発

このプロジェクトは uv + pnpm のモノレポで、Turbo がオーケストレーションを担います。 セットアップの詳細は 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 に記載されています。コントリビューションには Developer Certificate of Origin が適用されます（commit-msg フックが コミットに自動でサインオフします）。

Links