クイックスタート¶

このページでは、サーバーのインストール、認証情報の設定、5 分以内に最初の画像を生成するまでの手順を説明します。

注釈

このガイドは、すでにインストールを完了していることを前提としています。

1. サーバーを起動する (stdio)¶

デフォルトのトランスポートは stdio です — Claude Desktop や Cline のようなローカルエージェント向けです。フォアグラウンドプロセスとして実行します。

uv run python -m novelai_image_mcp serve

サーバーは stdin から読み取り、JSON-RPC レスポンスを stdout に書き出します。クライアントが接続するまで何も表示されません。終了するには Ctrl+C を押してください。

2. 画像を生成する (CLI)¶

MCP ホストを立ち上げずに手軽に試すには、同期の typer CLI を使用します。

uv run python -m novelai_image_mcp generate \
  --prompt "a cat sitting on a windowsill, masterpiece, best quality" \
  --width 832 \
  --height 1216

CLI は保存された PNG のパスを出力します。

outputs/generate-YYYYMMDD-HHMMSS-NNN.png

ファイルを開くと、生成された猫の画像が表示されます。

3. HTTP 経由で生成する¶

サーバーを HTTP 経由でリモートクライアントに公開するには、以下を実行します。

MCP_TRANSPORT=streamable-http uv run python -m novelai_image_mcp serve

サーバーはデフォルトで http://127.0.0.1:8000/mcp でリッスンします。ホストとポートは MCP_HOST / MCP_PORT で上書きできます。

4. Claude Desktop を接続する¶

claude_desktop_config.json を編集します (macOS: ~/Library/Application Support/Claude/、Windows: %APPDATA%\Claude\)。

{
  "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}"
      }
    }
  }
}

${input:novelai_token} はホスト側で定義されたシークレット参照です — お使いの MCP ホストのシークレット UI (Claude Desktop、Cline など) を参照してください。1 回限りのテストでは、リテラルトークンを直接記述することもできます。

代替案: uvx (公開パッケージ)¶

PyPI からインストールした場合、以下の省略記法が使えます。

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

ホストのシェルで NOVELAI_TOKEN を設定してください — uvx は親環境を引き継ぎます。

代替案: http (リモート / Docker)¶

サーバーを別の場所で実行している場合 (例: リモートホスト上で docker compose up)、ホストから URL に直接アクセスします。

{
  "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) に置き換えてください。

Claude Desktop を再起動すると、11 個のツールを備えた novelai-image MCP サーバーが登録されます。Claude に 「水彩画でキツネを描いて」 と頼んでみて、generate_image が呼び出される様子を観察してください。

その他のエージェントホスト (Cline、Cursor、Continue、Windsurf、Codex CLI) については、エージェントホスト (英語版) を参照してください。

5. アカウント残高を確認する¶

長時間の生成セッションの前に、Anlas 残高を確認しましょう。

uv run python -m novelai_image_mcp info

{
  "tier": 3,
  "active": true,
  "trainingStepsLeft": { "fixed": 10000, "perStepUsage": false },
  "subscriptionId": "..."
}

または、エージェントから get_subscription MCP ツールを呼び出します。

次のよくあるステップ¶

📚 各パラメータの詳細はツールリファレンス (英語版) を参照
🎨 チュートリアル (英語版) を試す — img2img、inpaint、アップスケール、ControlNet
🔧 環境変数で生成デフォルトを調整する
🐳 本番運用向けに Docker 化する (英語版)

トラブルシューティング¶

認証エラー

以下のようなエラーが表示された場合:

RuntimeError: NovelAI credentials are not configured: set NOVELAI_TOKEN or
NOVELAI_USERNAME + NOVELAI_PASSWORD (see .env.example).

.env ファイルが存在し、pst- で始まる有効な NOVELAI_TOKEN が含まれていることを確認してください。info サブコマンドは、Anlas を消費せずに認証を検証する最も手軽な方法です。

初回実行が遅い

初回の uv sync は約 60 個の wheel をダウンロードします。2 回目以降はキャッシュを再利用し、数秒で完了します。企業プロキシ環境下の場合は、 UV_HTTP_TIMEOUT=300 (秒) を設定して、遅いネットワークでのタイムアウトを回避してください。

画像が保存されない

NOVELAI_OUTPUT_DIR (デフォルト: outputs) を確認してください。ディレクトリはサーバーを実行するユーザーが書き込み可能である必要があります。Docker の場合、ディレクトリは /app/outputs で、名前付きボリューム (novelai-outputs) に裏打ちされています。