VLC MCP Server

VLC MCP サーバー

VLC メディアプレーヤーを使って動画を再生・操作するための MCP（Model Context Protocol）サーバーです。 任意の MCP クライアントを使って、動画をリモートで再生できます（例：awesome-mcp-clients）。

私は、プロジェクターに接続した古いノートパソコンで signal-mcp-client を実行しています。 これにより、Signal メッセージを送信して動画を再生できます。 使い方の例を以下のスクリーンショットに示します。

使い方

このインストール方法は、Ubuntu または Raspberry Pi OS のような Debian ベースのシステムを実行する Linux システム向けです。 いくつか変更を加えれば、ほかのシステムでも動作するはずです。 ほかのシステムで動作させることができた場合は、プルリクエストをお寄せください。

1. VLC、mediainfo、uv をインストールします。

   sudo apt-get install vlc mediainfo
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. VLC の HTTP サーバーを起動します。

   export DISPLAY=:0 # サーバー上でリモート実行する場合に必要です
   vlc --extraintf=http --http-host=localhost --http-port=8081 --http-password=your_password
   

3. クライアント（signal-mcp-client や awesome-mcp-clients など）の MCP 設定ファイルにサーバーを追加します。

   {
       "name": "vlc-mcp-server",
       "command": "uvx",
       "args": [
           "vlc-mcp-server"
       ],
       "env": {
           "ROOT_VIDEO_FOLDER": "path/to/your/video/folder",
           "VLC_HTTP_HOST": "localhost",
           "VLC_HTTP_PORT": "8081",
           "VLC_HTTP_PASSWORD": "your_password"
       }
   }
   

   または、リポジトリをクローンし、ディレクトリを指定して uv を使用します。

   {
       "name": "vlc-mcp-server",
       "command": "uv",
       "args": [
           "--directory",
           "path/to/root/dir/",
           "run",
           "vlc_mcp_player/main.py"
       ],
       "env": {
           "the same as above"
       }
   }
   

コントリビューション

このプロジェクトへの貢献を歓迎します。バグの報告、アイデアの提案、マージリクエストの作成など、お気軽にお寄せください。

開発

リポジトリをクローンし、依存関係をインストールします。

git clone https://github.com/piebro/vlc-mcp-server.git
uv venv
uv sync --extra dev
uv run pre-commit install

テスト

mcp-client-for-testing を使い、ローカルパスを使用する JSON 設定でサーバーのツールをテストします。

uvx mcp-client-for-testing \
    --config '
    [
        "the json config from above"
    ]
    ' \
    --client_log_level "INFO" \
	--server_log_level "INFO" \
    --tool_call '{"name": "show_video", "arguments": {"video_title": "David Lynch - Dune", "subtitle_language_code": "en"}}'

フォーマットとリント

コードのフォーマットとリントには ruff を使用します。

uv run ruff format
uv run ruff check --fix

uv でのビルド

uv を使ってパッケージをビルドします。

uv build

新しいバージョンのリリース

パッケージの新しいバージョンを PyPI にリリースするには、新しい Git タグを作成してプッシュします。

1. main ブランチをチェックアウトし、現在のバージョンを確認します。

   git checkout main
   git pull origin main
   git describe --tags
   

2. 新しい Git タグを作成してプッシュします。

   git tag v0.2.0
   git push origin v0.2.0
   

新しいタグがプッシュされると、GitHub Actions のワークフローによってパッケージが自動的にビルドされ、PyPI に公開されます。 Python パッケージのバージョン番号は、Git タグから直接取得されます。

Systemd サービスとして実行する

VLC の HTTP インターフェースが起動時に自動的に実行され、障害時に再起動するようにするには（Linux システムの場合）、systemd ユーザーサービスとして設定できます。 ユーザーサービスは、特定のユーザーアカウントで実行されます。

この設定では、セットアップ手順が完了していることを前提としています。

1. ユーザーのログアウト後もユーザーセッションをアクティブに保つため、ユーザーのリンギングを有効にします。

   sudo loginctl enable-linger $USER
   

2. Systemd サービスディレクトリを作成します

   mkdir -p /home/$USER/.config/systemd/user/
   

3. VLC HTTP サーバーのサービスファイルを作成します。 apt を使用して vlc をインストールしていることを確認してください。snap を使用している場合は、vlc バイナリへのパスを変更してください。

   cat << EOF > "/home/$USER/.config/systemd/user/vlc-http.service"
   [Unit]
   Description=VLC Media Player with HTTP Interface
   After=network.target sound.target
   
   [Service]
   Restart=on-failure
   RestartSec=30
   SyslogIdentifier=vlc-http
   Environment="DISPLAY=:0"
   
   ExecStart=/usr/bin/vlc --extraintf=http --http-host=localhost --http-port=8081 --http-password=your_password
   
   ExecStop=/usr/bin/pkill -f '/usr/bin/vlc --extraintf=http --http-host=localhost --http-port=8080'
   
   [Install]
   WantedBy=default.target
   EOF
   

4. サービスを有効にして起動します

   systemctl --user daemon-reload
   systemctl --user enable vlc-http.service
   systemctl --user start vlc-http.service
   

5. サービスのステータスとログを確認します

   systemctl --user status vlc-http.service
   journalctl --user -u vlc-http.service -f
   

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。