VLC Media Player

VLC MCP 服务：使用 Claude、ChatGPT 和 Ollama 控制 VLC Media Player

vlc-mcp 是一个 Model Context Protocol (MCP) 服务和 Claude Code 插件，可让 AI 客户端通过 VLC Media Player 内置的 HTTP 接口检查和控制 VLC。它默认使用 MCP stdio 供本地客户端使用，并提供可选的仅限环回连接的 Streamable HTTP 模式，用于 curl 冒烟测试和本地 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 配置中使用 vlc-mcp-server 作为 command，并将 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 密码，请将 VLC_HTTP_PASSWORD 添加到 env；除非配置了 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。打开聊天并让 Claude 列出 VLC 播放列表。有关当前 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 指南。

将 Ollama 模型与 MCP 主机搭配使用

Ollama 负责运行模型；请在连接该模型的 Agent 或客户端中配置 MCP 服务。Ollama 的 /api/chat 工具调用会从客户端获取函数定义，因此不会直接使用此服务的 MCP 配置。请使用 Hermes Agent 或 OpenClaw 等支持 MCP 的主机，然后将 Ollama 选为该主机的模型提供方。Ollama 的 ollama launch 可以设置受支持的 Agent 集成：

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 密码，请将 VLC_HTTP_PASSWORD 添加到配置的 env 中。随后，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、命令行和配置选项。

使用 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":{}}}'

响应可能以服务器发送事件（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 协议使用 stdout；服务不会向 stdout 写入应用日志。

发布到 MCP Registry

此仓库包含 server.json，以及 package.json 中与之匹配的 mcpName 字段，供官方 MCP Registry 使用。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。