VLC Media Player

VLC MCP サーバー：Claude、ChatGPT、Ollama で VLC Media Player を操作する

vlc-mcp は、組み込みの HTTP インターフェースを使用して、AI クライアントから VLC Media Player の状態を確認し、操作できる Model Context Protocol（MCP）サーバーおよび Claude Code プラグインです。ローカルクライアントでは、デフォルトで MCP stdio を使用します。また、curl によるスモークテストやローカル HTTP クライアント向けに、ループバック限定の Streamable HTTP モードも利用できます。

VLC のコーンアイコンは VideoLAN のものです。VLC とコーンのロゴは VideoLAN の商標です。この独立したプロジェクトは VideoLAN とは関係ありません。

できること

ツール	目的
vlc_get_status	再生状態、メディア、経過時間、再生時間、音量を取得します
vlc_list_playlist	メディア項目と対応する VLC プレイリスト ID を一覧表示します
vlc_play	再生を再開するか、ID を指定してプレイリスト項目を再生します
vlc_pause	再生の一時停止状態を切り替えます
vlc_stop	再生を停止します
vlc_next / vlc_previous	プレイリスト項目を切り替えます
vlc_set_volume	音量を 0～512 の範囲で設定します
vlc_seek	秒単位で再生位置を指定します
vlc_add_media	ローカルのメディアパス、または VLC がサポートするメディア URL をプレイリストに追加します

要件

• Node.js 20 以降
• HTTP インターフェースを有効にした VLC Media Player
• stdio 経由でローカルコマンドを起動できる MCP クライアント

npm でのクイックセットアップ

1. VLC を起動して HTTP インターフェースを有効にする

1. この MCP サーバーを実行するコンピューターに VLC Media Player をインストールして開きます。
2. ツール → 設定を開きます。左下で設定の表示をシンプルからすべてに変更します。
3. 左側のパネルでインターフェース → メインインターフェースを開き、Webにチェックを入れます。
4. インターフェース → メインインターフェース → Luaを開き、VLC の設定で必要な場合はLua HTTPパスワードを設定します。VLC ではユーザー名はデフォルトで空です。このサーバーでも、ユーザー名とパスワードはどちらもデフォルトで空です。設定を保存し、変更後に VLC を再起動します。
5. VLC の Web インターフェースはデフォルトのローカルアドレス http://127.0.0.1:8080 のままにします。HTTP インターフェースをインターネットに公開しないでください。

VLC の設定項目の名称は、バージョンによって多少異なる場合があります。この設定は VLC の Lua HTTP インターフェースの一部です。VLC サーバーにユーザー名を設定していない限り、ユーザー名は空欄のままにしてください。Lua HTTP パスワードを設定した場合は、MCP クライアントの環境変数 VLC_HTTP_PASSWORD に同じ値を設定します。

2. 公開済みの MCP サーバーを実行する

リポジトリのクローンやローカルでのビルドは不要です。公開済みの npm パッケージは npx で実行できます。初回起動時にパッケージがダウンロードされます。

npx -y vlc-mcp-server

このコマンドは MCP stdio サーバーを起動します。通常は AI クライアントの MCP 設定に追加し、クライアントから自動的に起動できるようにします。

グローバルにインストールするには、npm install --global vlc-mcp-server を実行します。その後、MCP 設定の command に vlc-mcp-server を指定し、空の args 配列を使用します。

3. AI クライアントにサーバーを追加する

AI クライアントの設定で mcpServers の下に、次のエントリを追加します。

{
  "vlc": {
    "command": "npx",
    "args": ["-y", "vlc-mcp-server"],
    "env": {
      "VLC_BASE_URL": "http://127.0.0.1:8080"
    }
  }
}

設定にすでに mcpServers オブジェクトがある場合は、ほかのサーバーエントリを残したまま vlc プロパティだけを追加します。ファイルを保存し、クライアントを再起動します。VLC に Lua HTTP パスワードを設定している場合は、env に VLC_HTTP_PASSWORD を追加します。ユーザー名を設定していない限り、VLC_HTTP_USERNAME は空のままにしてください。

4. AI に VLC の操作を依頼する

次のプロンプトを試してください。

• 「現在の VLC の再生状態を表示して。」
• 「VLC のプレイリストを一覧表示して。」
• 「メディアファイルを VLC のプレイリストに追加して。」
• 「プレイリストの最初の項目を再生して。」
• 「VLC を一時停止して、音量を 120 に設定して。」
• 「90 秒の位置に移動して。」

特定の項目を再生するには、まずプレイリストを表示し、その項目の数値 ID を vlc_play に渡します。vlc_add_media には、ローカルパスまたは VLC がサポートする URL を指定できます。VLC がファイルを読み取る、または URL にアクセスするための権限が必要です。

Claude Code プラグインとしてインストールする

/plugin marketplace add QuantumNovice/vlc-mcp
/plugin install vlc-mcp --marketplace QuantumNovice/vlc-mcp

Claude Desktop から接続する

Claude Desktop は stdio 経由でパッケージを起動できます。%APPDATA%\Claude\claude_desktop_config.json を開き（必要に応じて作成し）、mcpServers の下に次の設定を追加します。

{
  "vlc": {
    "command": "npx",
    "args": ["-y", "vlc-mcp-server"],
    "env": {
      "VLC_BASE_URL": "http://127.0.0.1:8080"
    }
  }
}

ファイルにほかの MCP サーバーがすでに含まれている場合は、mcpServers 内に vlc エントリのみを追加してください。ファイルを保存して、Claude Desktop を再起動します。チャットを開き、VLC のプレイリストを一覧表示するよう Claude に依頼します。現在の Claude Desktop 拡張機能のオプションについては、Anthropic のローカル MCP サーバーガイドを参照してください。

OpenAI から接続する

OpenAI Agents SDK（ローカル stdio）

ローカルで実行するアプリケーションの場合は、OpenAI Agents SDK for JavaScript をそのアプリケーションに npm install @openai/agents でインストールします。この例では、公開済みの VLC パッケージをローカルプロセスとして起動します。

import { Agent, MCPServerStdio, run } from "@openai/agents";

const server = new MCPServerStdio({
  name: "VLC",
  command: "npx",
  args: ["-y", "vlc-mcp-server"],
  env: {
    VLC_BASE_URL: "http://127.0.0.1:8080",
    VLC_HTTP_USERNAME: "",
    VLC_HTTP_PASSWORD: process.env.VLC_HTTP_PASSWORD ?? ""
  }
});

await server.connect();
try {
  const agent = new Agent({
    name: "VLC assistant",
    instructions: "Use the VLC tools to answer the user's request.",
    mcpServers: [server]
  });
  const response = await run(agent, "Show the current VLC playback status.");
  console.log(response.finalOutput);
} finally {
  await server.close();
}

アプリケーションの実行前に OPENAI_API_KEY を設定してください。VLC で Lua HTTP パスワードを設定した場合に限り、VLC_HTTP_PASSWORD を設定します。OpenAI の Agents SDK MCP ガイドでは、ローカルの stdio 接続と HTTP サーバー接続について説明しています。

ChatGPT または OpenAI Responses API

ChatGPT および OpenAI のホスト型 API リクエストは、このコンピューターの 127.0.0.1 エンドポイントに直接接続できません。これらのホスト型製品からこのローカル VLC サーバーを使用するには、OpenAI Secure MCP Tunnel を使用します。OpenAI Platform でトンネルを作成し、このコンピューターで tunnel-client を実行して、このサーバーのローカル stdio コマンドまたは HTTP エンドポイントを指定します。その後、ChatGPT にカスタム MCP サーバーとしてトンネルを追加するか、OpenAI Responses API の MCP ツールで tunnel_id を渡します。トンネルの設定とアクセスは、OpenAI Platform および ChatGPT ワークスペースの権限によって異なります。OpenAI のトンネルガイドを参照してください。

Hermes Agent から接続する

Hermes Agent はローカル stdio MCP サーバーに対応しています。Hermes の MCP CLI で公開済み npm パッケージを登録します。

hermes mcp add vlc --command npx --args -y vlc-mcp-server
hermes mcp test vlc

hermes chat で Hermes を起動または再起動し、VLC のステータスを表示するよう依頼します。サーバーのユーザー名とパスワードは、デフォルトでは空です。Lua HTTP パスワードを設定した場合は、Hermes の設定にある mcp_servers.vlc.env.VLC_HTTP_PASSWORD に追加します。Hermes の MCP 設定方法と設定オプションについては、Hermes MCP ガイドを参照してください。

MCP ホストで Ollama モデルを使用する

Ollama はモデルを実行します。MCP サーバーは、そのモデルに接続するエージェントまたはクライアントで設定してください。Ollama の /api/chat によるツール呼び出しでは、クライアントから関数定義を受け取るため、このサーバーの MCP 設定は直接使用されません。Hermes Agent や OpenClaw などの MCP 対応ホストを使用し、そのホストのモデルプロバイダーとして Ollama を選択してください。Ollama の ollama launch を使って、対応するエージェント連携を設定できます。

ollama pull qwen3
ollama launch hermes --model qwen3
# Or use OpenClaw:
ollama launch openclaw --model qwen3

その後、上記のセクションに従って Hermes または OpenClaw で vlc MCP サーバーを設定します。ツール呼び出しに対応したモデルを使用してください。ollama show qwen3 を実行すると、モデルの機能を確認できます。アプリケーションコードから直接使用する場合、アプリが MCP クライアントとして動作し、検出した MCP ツールを Ollama のチャット API に転送する必要があります。Ollama のツールサポートを参照してください。

llama.cpp から接続する

最近の llama-server ビルドは、stdio 経由の MCP サーバーに対応しています（この機能は実験的とされています）。Cursor 形式の次の MCP 設定を vlc-mcp-servers.json として保存します。

{
  "mcpServers": {
    "vlc": {
      "command": "npx",
      "args": ["-y", "vlc-mcp-server"],
      "env": {
        "VLC_BASE_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

設定ファイルがあるディレクトリから llama-server.exe を起動する際に、すでに使用しているコマンドへ次のオプションを追加します。

--mcp-servers-config vlc-mcp-servers.json

VLC に Lua HTTP パスワードが設定されている場合は、設定の env に VLC_HTTP_PASSWORD を追加します。MCP ツールは、モデルサーバーのほかのツールとともに登録されます。llama.cpp MCP サーバーのドキュメントを参照してください。

OpenClaw から接続する

OpenClaw はローカルの stdio MCP サーバーに対応しています。公開済みパッケージを追加し、ツールを確認します。

openclaw mcp add vlc `
  --command npx `
  --arg -y `
  --arg vlc-mcp-server
openclaw mcp doctor vlc --probe

確認結果に VLC のツールが表示されます。VLC のパスワードやその他の環境変数を設定するには、OpenClaw の Settings → MCP ページまたは mcp.servers 設定で vlc サーバーを編集します。VLC で Lua HTTP パスワードを設定していない限り、VLC_HTTP_PASSWORD は空のままにしてください。

OpenClaw の MCP ガイドでは、UI、CLI、設定オプションについて説明しています。

curl で MCP エンドポイントをテストする

MCP エンドポイントはデフォルトで stdio を使用します。curl でテストするには、オプションのローカル HTTP モードで公開済みパッケージを起動します。

$env:MCP_TRANSPORT = "http"
$env:MCP_HTTP_PORT = "3000"
npx -y vlc-mcp-server

そのウィンドウは起動したままにしてください。別の PowerShell ウィンドウで、MCP 接続を初期化します。

curl.exe -sS -X POST http://127.0.0.1:3000/mcp `
  -H "Content-Type: application/json" `
  -H "Accept: application/json, text/event-stream" `
  --data-raw '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-smoke-test","version":"1.0.0"}}}'

MCP ツールを一覧表示します。

curl.exe -sS -X POST http://127.0.0.1:3000/mcp `
  -H "Content-Type: application/json" `
  -H "Accept: application/json, text/event-stream" `
  --data-raw '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

VLC のステータスを呼び出します（VLC が起動しており、HTTP インターフェースが有効になっている必要があります）。

curl.exe -sS -X POST http://127.0.0.1:3000/mcp `
  -H "Content-Type: application/json" `
  -H "Accept: application/json, text/event-stream" `
  --data-raw '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"vlc_get_status","arguments":{}}}'

応答は Server-Sent Events（event: message に続いて JSON の data: 行）として返される場合があります。この HTTP モードは 127.0.0.1 にバインドされます。ローカルでの確認やローカルクライアントでの利用を目的としています。Ctrl+C で停止します。

5. 接続のトラブルシューティング

• 接続拒否またはタイムアウト： VLC が起動していること、Web インターフェースが有効になっていること、VLC_BASE_URL が VLC を実行しているコンピューターを指していることを確認してください。
• 401 Unauthorized： VLC_HTTP_USERNAME は空のままにしてください。VLC で Lua HTTP パスワードを設定している場合は、その値を VLC_HTTP_PASSWORD にコピーし、MCP クライアントを再起動します。設定していない場合は、両方の値を空のままにしてください。
• メディアが再生されない： VLC で同じファイルまたは URL を直接開けることを確認してください。VLC を実行しているコンピューター上にパスが存在することを確認します。

環境変数

変数	デフォルト	説明
VLC_BASE_URL	http://127.0.0.1:8080	VLC HTTP インターフェースの URL
VLC_HTTP_USERNAME	empty	VLC の HTTP/Lua インターフェースのユーザー名
VLC_HTTP_PASSWORD	empty	VLC の HTTP/Lua インターフェースに設定したパスワード
VLC_HTTP_TIMEOUT_MS	5000	リクエストのタイムアウト。100～120000 ミリ秒
MCP_TRANSPORT	stdio	MCP トランスポート：stdio またはローカルの http
MCP_HTTP_PORT	3000	ローカル HTTP モードのポート

ソースからビルドする

npm パッケージを使用する代わりにサーバーのソースを編集するには、クローンしてビルドします。

git clone https://github.com/QuantumNovice/vlc-mcp.git
Set-Location .\vlc-mcp
npm install
npm run build

ビルドしたサーバーを npm start で実行します。標準入力／出力で MCP クライアントからの接続を待ち受けます。MCP プロトコルは標準出力を使用します。サーバーはアプリケーションのログを標準出力に書き込みません。

MCP Registry への公開

このリポジトリには、公式 MCP Registry 用の server.json と、package.json 内の対応する mcpName フィールドが含まれています。Registry は MCP サーバーを掲載するものであり、GitHub Apps と Actions を公開する GitHub Marketplace とは別のものです。このサーバーを MCP Registry に登録するには、まず npm パッケージと GitHub リポジトリを公開し、その後、認証して公式 CLI で公開します。

npm publish --access public
mcp-publisher login github
mcp-publisher validate
mcp-publisher publish

server.json と package.json の Registry 名前空間は io.github.QuantumNovice/vlc-mcp です。公開前に、設定された URL で GitHub リポジトリを作成してください。Registry への公開には、この名前空間を管理するアカウントでの GitHub 認証が必要です。

セキュリティに関する注意事項

• VLC の HTTP インターフェースは localhost にバインドしたままにしてください。VLC の HTTP インターフェースにはトランスポート暗号化がないため、信頼できないネットワークに直接公開しないでください。パスワードを設定する場合は、強力なものを使用してください。
• vlc_add_media ツールは入力を VLC に渡します。VLC はネットワーク URL や、VLC プロセスがアクセスできるローカルファイルを開く場合があります。信頼できる MCP クライアントのみを接続し、VLC が開いても問題のないメディアへのアクセス権を付与してください。
• サーバーは設定された VLC_BASE_URL にのみリクエストを送信します。信頼できないエンドポイントを設定しないでください。

ライセンス

MIT。詳しくは LICENSE を参照してください。