sd-api-mcp 0.3.0

MCP server wrapping the Stable Diffusion WebUI API

SD API MCP

Stable Diffusion WebUI API (AUTOMATIC1111/ForgeUI) を操作する MCP サーバ

前提条件

• Stable Diffusion WebUI（または ForgeUI）が起動していること
• uv がインストール済みであること

MCPクライアント設定

Claude Code

claude mcp add sd-api-mcp uvx sd-api-mcp

または .claude/settings.json に追加:

{
  "mcpServers": {
    "sd-api-mcp": {
      "command": "uvx",
      "args": ["sd-api-mcp"],
      "env": {
        "SD_WEBUI_URL": "http://localhost:7860"
      }
    }
  }
}

Cursor

.cursor/mcp.json に追加:

{
  "mcpServers": {
    "sd-api-mcp": {
      "command": "uvx",
      "args": ["sd-api-mcp"],
      "env": {
        "SD_WEBUI_URL": "http://localhost:7860"
      }
    }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json に追加:

{
  "servers": {
    "sd-api-mcp": {
      "command": "uvx",
      "args": ["sd-api-mcp"],
      "env": {
        "SD_WEBUI_URL": "http://localhost:7860"
      }
    }
  }
}

環境変数

変数名	デフォルト	説明
SD_WEBUI_URL	http://host.docker.internal:7860	SD WebUI のベース URL
SD_AUTH_USER	（なし）	Basic 認証ユーザー名（任意）
SD_AUTH_PASS	（なし）	Basic 認証パスワード（任意）
SD_OUTPUT_DIR	./output	生成画像の保存先ディレクトリ
REQUEST_TIMEOUT	300	HTTP リクエストのタイムアウト秒数

ツールリファレンス

txt2img

テキストプロンプトから画像を生成し、ファイルに保存します。

パラメータ	型	デフォルト	説明
prompt	str	必須	生成プロンプト
negative_prompt	str	""	ネガティブプロンプト
steps	int	20	サンプリングステップ数（1〜150）
width	int	512	画像の幅 px（64〜2048）
height	int	512	画像の高さ px（64〜2048）
cfg_scale	float	7.0	CFG スケール（1.0〜30.0）
sampler_name	str	"Euler a"	サンプラー名
scheduler_name	str	"Automatic"	スケジューラー名
seed	int	-1	シード値（-1 でランダム）
batch_size	int	1	生成枚数（1〜4）
restore_faces	bool	false	顔修復を有効にする
tiling	bool	false	タイリング画像を生成する
distilled_cfg_scale	float	3.5	Distilled CFG スケール（1.0〜30.0）
controlnet_units	list	null	ControlNet ユニットのリスト
output_dir	str	"./output"	出力ディレクトリ

戻り値: 生成された画像ファイルの絶対パスリスト

img2img

入力画像とプロンプトから画像を生成し、ファイルに保存します。

パラメータ	型	デフォルト	説明
init_image	str	必須	入力画像のファイルパス
prompt	str	必須	生成プロンプト
negative_prompt	str	""	ネガティブプロンプト
denoising_strength	float	0.75	デノイズ強度（0.0〜1.0）
steps	int	20	サンプリングステップ数（1〜150）
width	int	512	画像の幅 px（64〜2048）
height	int	512	画像の高さ px（64〜2048）
cfg_scale	float	7.0	CFG スケール（1.0〜30.0）
sampler_name	str	"Euler a"	サンプラー名
scheduler_name	str	"Automatic"	スケジューラー名
seed	int	-1	シード値（-1 でランダム）
batch_size	int	1	生成枚数（1〜4）
restore_faces	bool	false	顔修復を有効にする
tiling	bool	false	タイリング画像を生成する
controlnet_units	list	null	ControlNet ユニットのリスト
output_dir	str	"./output"	出力ディレクトリ

戻り値: 生成された画像ファイルの絶対パスリスト

get_sd_models

利用可能な Stable Diffusion モデルの一覧を返します。

パラメータなし。戻り値: モデル名の文字列リスト

set_sd_model

アクティブな Stable Diffusion モデルを変更します。

パラメータ	型	デフォルト	説明
model_name	str	必須	設定するモデル名

戻り値: 設定完了メッセージ（文字列）

get_sd_upscalers

利用可能なアップスケーラーの一覧を返します。

パラメータなし。戻り値: アップスケーラー名の文字列リスト

upscale_images

画像をアップスケールして保存します。

パラメータ	型	デフォルト	説明
images	list[str]	必須	アップスケールする画像ファイルパスのリスト
resize_mode	int	0	0=倍率指定, 1=サイズ指定
upscaling_resize	float	4.0	アップスケール倍率（resize_mode=0 時）
upscaling_resize_w	int	512	目標幅 px（resize_mode=1 時）
upscaling_resize_h	int	512	目標高さ px（resize_mode=1 時）
upscaler_1	str	"R-ESRGAN 4x+"	プライマリアップスケーラー
upscaler_2	str	"None"	セカンダリアップスケーラー
output_dir	str	"./output"	出力ディレクトリ

戻り値: 保存された画像ファイルの絶対パスリスト

get_controlnet_models

利用可能な ControlNet モデルの一覧を返します。

パラメータなし。戻り値: ControlNet モデル名の文字列リスト

get_controlnet_modules

利用可能な ControlNet プリプロセッサの一覧を返します。

パラメータなし。戻り値: ControlNet プリプロセッサ名の文字列リスト

開発者向け

環境構築

git clone https://github.com/HizZaniya/sd-api-mcp.git
cd sd-api-mcp
uv sync --group dev
pre-commit install

テスト実行

uv run pytest -v

型チェック・Lint:

uv run ty check
uv run ruff check .
uv run ruff format --check .

ファイル構成

src/sd_api_mcp/
├── server.py   # MCP プロトコル層 — ツール定義・リクエスト受付
└── client.py   # SD WebUI API 通信層 — httpx による HTTP クライアント

• server.py: FastMCP のツールデコレータでツールを定義し、MCP プロトコルを処理する。SD WebUI への直接アクセスは行わない。
• client.py: httpx を使って SD WebUI の REST API と通信する。MCP プロトコルを知らない。

リリース手順

1. Conventional Commits 形式でコミットを積む（例: feat: add new tool, fix: handle timeout）
2. GitHub Actions の Release ワークフローを手動トリガーする
3. cz bump がコミット履歴からバージョンを自動決定し、CHANGELOG.md を更新してタグを作成
4. Publish ワークフローが自動実行され、TestPyPI で検証後 PyPI に公開される

コントリビューション

1. main ブランチから feature ブランチを作成する
2. テストを先に書いてから実装する（TDD）
3. PR を作成する（テンプレートに従うこと）
4. CI（lint / format / typecheck / test）がすべてパスしたらレビューを依頼する

コミットメッセージは Conventional Commits 形式を推奨します。

ライセンス

MIT