utauMCP

OpenUtau (歌声合成ソフト) を Claude Desktop から操作するための MCP サーバー、 および OpenUtau内蔵のリアルタイム連携プラグイン。

ymm4MCP と同じ立ち位置: Claude Desktop の claude_desktop_config.json に 登録して使うMCPサーバー本体(Python)と、OpenUtau自体に読み込ませる プラグイン(C#, plugin/UtauMcpBridge)の2部構成。実機で動作確認済み。

構成

utauMCP/
  server.py                MCPサーバー本体 (FastMCP, 全ツール定義)
  utau_mcp/
    config.py              OpenUtauのデータフォルダ(Singers等)をOSごとに検出
    ustx.py                .ustx (YAML) の読み書き・ノート/トラック/パート操作 (ファイルベース)
    lyrics.py               歌詞のモーラ分割・自動ノート割り当て
    voicebank.py             Singersフォルダのスキャン・oto.ini解析
    ust_legacy.py            クラシック.ustの読み書き (Shift_JIS対応)
    automation.py            OpenUtauプロセスの起動/終了/検出
    bridge_client.py         plugin/UtauMcpBridge と通信するHTTPクライアント (ライブ連携)
  plugin/UtauMcpBridge/      OpenUtau本体に読み込ませるC#プラグイン (下記)
  skills/utau-mcp/SKILL.md   Claude向けの使い方ガイド

2つの操作方式

	ファイルベース (ustx.py)	ライブブリッジ (bridge_client.py)
前提	常に使える	OpenUtauで音源のフォニマイザーに「[MCP] Claude連携ブリッジ」を選択済み
反映タイミング	保存時。OpenUtau起動中なら開き直しが必要	即座に画面へ反映 (保存・開き直し不要)
できること	プロジェクト全体の作成・編集	現在開いているプロジェクトの編集・保存

Claudeは基本的に is_bridge_available() で確認し、使えれば *_live ツールを、 使えなければファイルベースのツールを使う。

plugin/UtauMcpBridge (OpenUtau内蔵プラグイン)

OpenUtauの「Plugins」フォルダに .dll を1つ置くと、OpenUtau起動時に自動で 読み込まれる。重要: OpenUtau 0.1.565 (実際にリリースされているバージョン) には汎用プラグイン拡張点(BatchEdit等)が無く、唯一サードパーティdllが 実際にロードされる仕組みはフォニマイザー(OpenUtau.Api.Phonemizer 継承クラス)だけ。そのため、あえてフォニマイザーとして登録し:

• 音源のフォニマイザー選択ドロップダウン(「さらに表示」の中)に 「[MCP] Claude連携ブリッジ (発音処理はしません)」 という項目が追加される。
• これを選択すると(コンストラクタが走り)http://127.0.0.1:51127/ (localhost限定、認証なし)でHTTPサーバーが起動する。起動処理は冪等で、 内部で複数回コンストラクタが呼ばれても問題ない。
• DocManager.Inst (今開いているプロジェクトの実体)に直接アクセスし、 ノート追加/編集/削除・保存を、ファイルを介さず即座にOpenUtauの画面へ反映する。
• Process() は空の音素配列を返すダミー実装 (実際の発音・レンダリングはしない)。

ビルド方法

OpenUtau本体と型を一致させるため、実際にインストールされているバージョンの タグ付きソースでビルドする(masterブランチは先行開発中のAPIを含み、 型が一致してもリフレクションで検出されない/動作しないことがあるため使わない)。

git clone --branch <実際のバージョンタグ, 例: 0.1.565> https://github.com/stakira/OpenUtau.git
# UtauMcpBridge.csproj の <ProjectReference> パスをそこに合わせて書き換える
cd plugin/UtauMcpBridge
dotnet build
# 出力された UtauMcpBridge.dll を OpenUtauのPluginsフォルダにコピー
# (例: %USERPROFILE%\Documents\OpenUtau\Plugins\ または OneDriveのドキュメント配下)

バージョン確認方法: OpenUtauの ヘルプ メニューやログファイル (Logs/logYYYYMMDD.txt 冒頭の OpenUtau vX.X.X.X)で確認できる。

使い方 (OpenUtau側)

1. OpenUtauでプロジェクトを開く。
2. Track1などの「シンガーを選択」の下にあるフォニマイザー名をクリックし、 出てきたリストの「さらに表示 ...」を開く。
3. 「[MCP] Claude連携ブリッジ (発音処理はしません) (Contributed by utauMCP)」を選択。
4. これでClaude側から is_bridge_available() がTrueを返すようになる。
5. 一度選択すると、そのプロジェクトを開き直したときも自動的に再起動する (フォニマイザー選択がプロジェクトに保存されるため)。

注意: このフォニマイザーは実際の歌声合成をしないダミーなので、 本当に歌わせたいトラックには使わないこと(レンダリングしても無音になる)。 歌わせる用途では、ブリッジ操作が終わったら通常のフォニマイザー (JapaneseCVVCPhonemizer等)に選び直すこと。

Pythonサーバーのセットアップ

cd utauMCP
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

claude_desktop_config.json に claude_desktop_config_example.json の内容を マージして追加し、Claude Desktop を再起動する。

tick と拍の関係

OpenUtau は 1拍(四分音符) = 480 tick 固定。convert_beats_ticks ツールで相互変換できる。

ノート生成時の注意 (プラグイン開発者向け)

C#側でノートを新規作成する際は UNote.Create() を単体で使わず、 project.CreateNote(tone, position, duration) を使うこと。 UNote.Create() だけだとピッチカーブの初期点が無く、snapFirst=true の デフォルトと組み合わさって検証時に ArgumentOutOfRangeException で クラッシュする(実際に踏んだ罠)。CreateNote() は自動でポルタメントの 初期ピッチポイントを追加してくれる。

ファイル形式について

.ustx は YAML (UTF-8, snake_case キー)。本リポジトリの実装は stakira/OpenUtau 本家ソース (OpenUtau.Core/Ustx/*.cs, OpenUtau.Core/Format/USTx.cs) と、 実際に生成されたプロジェクトファイルを突き合わせて検証している。

今後の拡張候補

• レンダリング実行・再生プレビューをブリッジ経由で直接トリガーする (現状はノート編集・保存のみ対応)。
• YMM4MCPとの連携 (UTAUで作った歌声を動画の音声トラックに自動配置)。
• 複数キャラクター(音源)の歌唱切り替えの高レベルAPI化。