mml-composemusic-mcp

LLMにMMLを書かせ、レトロゲーム機風の音楽をWAVとして生成するMCPサーバです。

Pulse 2ch、Triangle 1ch、Noise 1chの構成を持つ簡易2A03 APU風シンセサイザーを内蔵しています。MCPクライアントから単一のcompose_mmlツールを呼び出すことで、作曲、検証、作例テンプレートの取得まで行えます。

主な機能

• MMLを解析し、モノラル16-bit PCMのWAVファイルを生成

• 構文・値域・チャンネル適合性を合成前に検証

• Pulse1、Pulse2、Triangle、Noiseの4チャンネルに対応

• ppmck風の小文字MMLと、Pyxel風の大文字MMLに対応

• 音量・音色エンベロープ、ビブラート、LFO、グライド、スイープなどを合成へ反映

• LLMがコピーして改変できる8種類の作例テンプレートを収録

• stdio、HTTP、SSE、Streamable HTTPトランスポートに対応

Related MCP server: chord-player-mcp

サンプルデータ

実際にLLMを使用してこのMCPツールで作曲させてみたサンプルデータです。

ppmck版

• 音声

• mml

pyxel版

• 音声

• mml

必要環境

• Python 3.14以上

• uv（推奨）

セットアップ

リポジトリを取得し、プロジェクトのディレクトリで依存関係をインストールします。

uv sync
uv run mml-composemusic-mcp --help

pipを使う場合は、仮想環境内で次のようにインストールできます。

python -m pip install -e .
mml-composemusic-mcp --help

MCPクライアントへの登録

標準入出力で起動する設定例です。C:\path\to\mml-composemusic-mcpと出力先を実際の絶対パスへ置き換えてください。

{
  "mcpServers": {
    "mml-composemusic": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "C:\\path\\to\\mml-composemusic-mcp",
        "mml-composemusic-mcp",
        "--output-dir",
        "C:\\path\\to\\mml-composemusic-mcp\\data"
      ]
    }
  }
}

--output-dirを省略した場合は、サーバの作業ディレクトリにある./dataへ出力します。MCPクライアントによって作業ディレクトリが異なるため、通常は絶対パスの指定を推奨します。

HTTP系トランスポートで手動起動する場合は、次のオプションを利用できます。

uv run mml-composemusic-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8080 \
  --output-dir ./data

利用可能な--transportはstdio（デフォルト）、http、sse、streamable-httpです。HTTP側の接続URLは、使用するFastMCPとMCPクライアントのトランスポート設定に合わせてください。

LLMからの使い方

公開されるツールはcompose_mmlの1つです。基本的には、テンプレートを取得して編集し、検証してから合成します。

1. action: "template"で作例を取得する

2. 作りたい曲に合わせてLLMがMMLを書き換える

3. action: "validate"でエラーと警告を確認する

4. 問題がなければaction: "compose"でWAVを生成する

MCPクライアントでは、たとえば次のように依頼できます。

pyxelモードのvibrato_leadテンプレートを参考に、テンポ150の明るい8小節のボス戦BGMを作ってください。まずvalidateし、問題を直してからcomposeしてください。

compose_mmlの引数

未知のmodeをtemplateで指定した場合はppmck、未知のテンプレート名を指定した場合はbasicへフォールバックします。validate/composeではmmlとmodeが必須です。

テンプレートを取得する

{
  "action": "template",
  "mode": "pyxel",
  "template": "vibrato_lead"
}

テンプレートは両モードに用意され、同じ目的を各モード固有のコマンドで表現します。

MMLを検証する

{
  "action": "validate",
  "mode": "ppmck",
  "mml": "A t120 l8 o4 v15 q7 @2\n  c d e f | g a b >c"
}

valid、errors、warningsに加え、解析済みのnote_sequenceとチャンネルごとのchannel_summaryを返します。エラーには行・列、原因、修正ヒントが含まれます。

WAVを生成する

{
  "action": "compose",
  "mode": "pyxel",
  "mml": "0: T120 L8 O4 V100 Q90 @1\n   C D E F | G A B >C",
  "sample_rate": 44100,
  "normalize": true
}

成功時は、MCPレスポンスのcontentにaudio/wavのAudioContentを返します。WAVデータはbase64エンコードされ、ファイルサイズにかかわらず同じ形式で返されます。structuredContentにはsuccess: true、duration_sec、音声メタデータ、解析済みのnote_sequence、検証結果が入ります。

指定した出力ディレクトリの下には、従来どおり生成時刻を表すYYYYMMDD_HHMMSS_mmmディレクトリを作り、output.wavと合成に使用したMML原文のoutput.mmlを保存します。この保存先はサーバ内部の情報であり、MCPレスポンスにはファイルパスを含めません。

MCPツールとしての成否はisErrorで判定します。compose、引数、actionなどのエラーはisError: true、正常に完了したvalidateは対象MMLが不正でもisError: falseです。composeのsuccessとvalidateのvalidは、それぞれの処理結果を表す構造化フィールドです。

MMLの書き方

チャンネル対応

ppmckは音符と基本コマンドに小文字、pyxelは大文字を使います。

ppmckモード

#TITLE "My Song"
#COMPOSER "LLM"

A t150 l8 o4 v15 q7 @2
  c d e f | g a b >c

B l8 o3 v11 @1
  c r g r | c r g r

T l4 o2 v7
  c2 g2 | a2 f2

N l8 v10
  c r c c | c r c r

主な拡張機能:

• D: セント単位のデチューン

• s: Pulseハードウェアスイープ

• v+ / v-: 相対音量

• @v / @@: 音量・デューティエンベロープ

• @MP / MP / MPOF: LFOの定義・適用・解除

• @EP / EP / EPOF: ピッチエンベロープ

• @EN / EN / ENOF: 高速アルペジオ向けノートエンベロープ

• ^: タイ、&: スラー

pyxelモード

0: T150 L8 O4 V110 Q90 @1
   C D E F | G A B >C

1: L8 O3 V80 @2
   C R G R | C R G R

2: L4 O2 V60
   C2 G2 | A2 F2

3: L8 V80
   C R C C | C R C R

主な拡張機能:

• K: 半音単位のトランスポーズ

• Y: セント単位のデチューン

• @ENV: 音量エンベロープ

• @VIB: ビブラート

• @GLI: グライド

• [...]N: 回数付きリピート

• &: スラー

値域や正確な文法はMML構文規則、MCPの入出力はMCPツール仕様、内部構造は設計書を参照してください。

現在の制約

• DPCM、NSF出力、GUI、Webプレイヤーはありません。

• 実機や既存ドライバの音を厳密に再現するエミュレーターではありません。

• Pulse専用コマンドをTriangleやNoiseへ指定すると、エラーまたは警告になります。

• ppmckの区間リピートなど、設計上予約されていても未実装の構文があります。

• pyxelの無限リピートは安全のため有限回で打ち切られ、警告が返る場合があります。

開発

# 全テスト
uv run pytest

# lint
uv run ruff check .

# format
uv run ruff format .

# stdioサーバを手動起動
uv run mml-composemusic-mcp --output-dir ./data

受理するMML文法を変更する場合は、実装・テストと合わせてdoc/MML_BNF.mdを更新してください。

変更履歴

CHANGELOG.mdを参照してください。

ライセンス

MIT