VLC MCP

vlc-mcp es un servidor de Model Context Protocol (MCP) y un plugin de Claude Code que permite a los clientes de IA inspeccionar y controlar VLC Media Player mediante su interfaz HTTP integrada.

GitHub

Documentación

Servidor VLC MCP: controla VLC Media Player con Claude, ChatGPT y Ollama

vlc-mcp es un servidor de Protocolo de Contexto de Modelo (MCP) y un plugin de Claude Code que permite a los clientes de IA inspeccionar y controlar VLC Media Player mediante su interfaz HTTP integrada. Utiliza MCP stdio por defecto para clientes locales, con un modo opcional de HTTP Streamable solo de loopback para comprobaciones con curl y clientes HTTP locales.

El icono del cono de VLC proviene de VideoLAN. VLC y el logotipo del cono son marcas comerciales de VideoLAN; este proyecto independiente no está afiliado a VideoLAN.

Qué puede hacer

Herramienta	Propósito
`vlc_get_status`	Leer el estado de reproducción, el medio, el tiempo transcurrido, la duración y el volumen
`vlc_list_playlist`	Listar los elementos multimedia y sus IDs de lista de reproducción de VLC
`vlc_play`	Reanudar la reproducción, o reproducir un elemento de la lista por ID
`vlc_pause`	Alternar el estado de pausa de la reproducción
`vlc_stop`	Detener la reproducción
`vlc_next` / `vlc_previous`	Cambiar el elemento de la lista de reproducción
`vlc_set_volume`	Establecer el volumen de 0 a 512
`vlc_seek`	Buscar una posición en segundos
`vlc_add_media`	Añadir una ruta de medio local o una URL de medio compatible con VLC a la lista de reproducción

Requisitos

Node.js 20 o posterior
VLC Media Player con la interfaz HTTP habilitada
Un cliente MCP que pueda lanzar un comando local a través de stdio

Configuración rápida con npm

1. Inicia VLC y habilita su interfaz HTTP

Instala y abre VLC Media Player en el mismo ordenador donde se ejecutará este servidor MCP.
Abre Herramientas → Preferencias. En la parte inferior izquierda, cambia Mostrar ajustes de Simple a Todos.
En el panel izquierdo, abre Interfaz → Interfaces principales y marca Web.
Abre Interfaz → Interfaces principales → Lua y establece la contraseña Lua HTTP si tu configuración de VLC lo requiere. VLC usa un nombre de usuario vacío por defecto; este servidor también establece tanto el nombre de usuario como la contraseña en vacío por defecto. Guarda las preferencias y reinicia VLC después de cambiarlas.
Mantén la interfaz web de VLC en su dirección local predeterminada, http://127.0.0.1:8080. No expongas la interfaz HTTP a internet.

Las etiquetas de preferencias de VLC pueden variar ligeramente según la versión. El ajuste forma parte de la interfaz Lua HTTP de VLC. Deja el nombre de usuario en blanco a menos que tu servidor VLC esté configurado con un nombre de usuario. Si estableces una contraseña Lua HTTP, configura VLC_HTTP_PASSWORD con el mismo valor en el entorno del cliente MCP.

2. Ejecuta el servidor MCP publicado

No se necesita clonar ni compilar localmente. El paquete npm publicado se puede ejecutar con npx; descarga el paquete en el primer lanzamiento:

npx -y vlc-mcp-server

El comando inicia el servidor MCP stdio. Normalmente, colócalo en la configuración MCP de tu cliente de IA para que el cliente lo inicie automáticamente.

Para instalarlo globalmente en su lugar, ejecuta npm install --global vlc-mcp-server; luego usa vlc-mcp-server como command de configuración MCP con un array args vacío.

3. Añade el servidor a tu cliente de IA

Añade esta entrada bajo mcpServers en la configuración de tu cliente de IA:

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

Si la configuración ya tiene un objeto mcpServers, añade solo la propiedad vlc y conserva las demás entradas del servidor. Guarda el archivo y reinicia el cliente. Si VLC tiene una contraseña Lua HTTP, añade VLC_HTTP_PASSWORD a env; deja VLC_HTTP_USERNAME vacío a menos que hayas configurado uno.

4. Pide a la IA que controle VLC

Prueba estas indicaciones:

"Muestra el estado de reproducción actual de VLC."
"Lista la lista de reproducción de VLC."
"Añade un archivo multimedia a la lista de reproducción de VLC."
"Reproduce el primer elemento de la lista de reproducción."
"Pausa VLC y establece el volumen a 120."
"Busca hasta los 90 segundos."

Para reproducir un elemento específico, primero pide la lista de reproducción y luego pasa el ID numérico del elemento a vlc_play. vlc_add_media acepta una ruta local o una URL compatible con VLC. VLC necesita permiso para leer el archivo o acceder a la URL.

Instalar como plugin de Claude Code

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

Conectar desde Claude Desktop

Claude Desktop puede lanzar el paquete a través de stdio. Abre %APPDATA%\Claude\claude_desktop_config.json (críalo si es necesario) y añade esto bajo mcpServers:

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

Si el archivo ya contiene otros servidores MCP, añade solo la entrada vlc dentro de mcpServers. Guarda el archivo y reinicia Claude Desktop. Abre un chat y pide a Claude que liste la lista de reproducción de VLC. Para las opciones actuales de extensiones de Claude Desktop, consulta la guía de servidores MCP locales de Anthropic.

Conectar desde OpenAI

OpenAI Agents SDK (stdio local)

Para una aplicación que ejecutes localmente, instala el OpenAI Agents SDK para JavaScript en esa aplicación con npm install @openai/agents. Este ejemplo inicia el paquete VLC publicado como un proceso local:

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();
}

Configura OPENAI_API_KEY antes de ejecutar la aplicación. Configura VLC_HTTP_PASSWORD solo si has configurado una contraseña Lua HTTP en VLC. La guía MCP de Agents SDK de OpenAI documenta las conexiones de servidor stdio local y HTTP.

ChatGPT o la API de Respuestas de OpenAI

ChatGPT y las solicitudes de API alojadas de OpenAI no pueden conectarse directamente al endpoint 127.0.0.1 de este ordenador. Para usar este servidor VLC local desde esos productos alojados, usa OpenAI Secure MCP Tunnel. Crea un túnel en OpenAI Platform, ejecuta tunnel-client en este ordenador y apúntalo al comando stdio local o al endpoint HTTP de este servidor. Luego añade el túnel en ChatGPT como un servidor MCP personalizado, o pasa su tunnel_id en una herramienta MCP de la API de Respuestas de OpenAI. La configuración y el acceso al túnel dependen de los permisos de tu OpenAI Platform y del espacio de trabajo de ChatGPT; consulta la guía de túneles de OpenAI.

Conectar desde Hermes Agent

Hermes Agent admite servidores MCP stdio locales. Registra el paquete npm publicado con la CLI MCP de Hermes:

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

Inicia o reinicia Hermes con hermes chat, luego pídele que muestre el estado de VLC. El servidor usa nombre de usuario y contraseña vacíos por defecto. Si has configurado una contraseña Lua HTTP, añádela bajo mcp_servers.vlc.env.VLC_HTTP_PASSWORD en la configuración de Hermes. La configuración y las opciones de MCP de Hermes están documentadas en la guía MCP de Hermes.

Usar modelos Ollama con un host MCP

Ollama ejecuta el modelo; configura el servidor MCP en el agente o cliente que se conecta a ese modelo. La llamada a herramientas /api/chat de Ollama toma definiciones de funciones del cliente, por lo que no usa la configuración MCP de este servidor directamente. Usa un host compatible con MCP como Hermes Agent o OpenClaw, y luego selecciona Ollama como proveedor de modelos de ese host. El ollama launch de Ollama puede configurar integraciones de agentes compatibles:

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

Luego configura el servidor MCP vlc en Hermes u OpenClaw usando la sección anterior. Usa un modelo con soporte de llamada a herramientas; ollama show qwen3 muestra las capacidades del modelo. Para código de aplicación directo, tu aplicación debe actuar como cliente MCP y reenviar las herramientas MCP descubiertas a la API de chat de Ollama; consulta soporte de herramientas de Ollama.

Conectar desde llama.cpp

Las compilaciones recientes de llama-server admiten servidores MCP a través de stdio (la función está marcada como experimental). Guarda esta configuración MCP estilo Cursor como vlc-mcp-servers.json:

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

Añade esta opción al comando que ya usas para iniciar llama-server.exe desde el directorio que contiene el archivo de configuración:

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

Si VLC tiene una contraseña Lua HTTP, añade VLC_HTTP_PASSWORD al env de la configuración. Las herramientas MCP se registran junto con las otras herramientas del servidor de modelos. Consulta la documentación del servidor MCP de llama.cpp.

Conectar desde OpenClaw

OpenClaw admite servidores MCP stdio locales. Añade el paquete publicado y prueba sus herramientas:

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

La prueba debería listar las herramientas de VLC. Para establecer una contraseña de VLC u otros valores de entorno, edita el servidor vlc en la página Configuración → MCP de OpenClaw o su configuración mcp.servers. Mantén VLC_HTTP_PASSWORD vacío a menos que hayas establecido una contraseña Lua HTTP en VLC.

La guía MCP de OpenClaw documenta la interfaz de usuario, la CLI y las opciones de configuración.

Probar el endpoint MCP con curl

El endpoint MCP usa stdio por defecto. Para probar con curl, inicia el paquete publicado en su modo HTTP local opcional:

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

Deja esa ventana abierta. En una segunda ventana de PowerShell, inicializa una conexión 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"}}}'

Lista las herramientas 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"}'

Llama al estado de VLC (VLC debe estar ejecutándose y su interfaz HTTP habilitada):

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

Las respuestas pueden devolverse como Server-Sent Events (event: message seguido de una línea JSON data:). Este modo HTTP está vinculado a 127.0.0.1; es para comprobaciones locales y clientes locales. Detenlo con Ctrl+C.

5. Solucionar problemas de conexión

Conexión rechazada o tiempo de espera agotado: Asegúrate de que VLC esté abierto, la interfaz Web esté habilitada y VLC_BASE_URL apunte al ordenador que ejecuta VLC.
401 No autorizado: Deja VLC_HTTP_USERNAME vacío. Si has establecido una contraseña Lua HTTP en VLC, cópiala en VLC_HTTP_PASSWORD y reinicia el cliente MCP. Si no has establecido una, mantén ambos valores vacíos.
El medio no se reproduce: Confirma que VLC puede abrir el mismo archivo o URL directamente. Verifica que la ruta exista en el ordenador que ejecuta VLC.

Variables de entorno

Variable	Predeterminado	Descripción
`VLC_BASE_URL`	`http://127.0.0.1:8080`	URL de la interfaz HTTP de VLC
`VLC_HTTP_USERNAME`	vacío	Nombre de usuario para la interfaz HTTP/Lua de VLC
`VLC_HTTP_PASSWORD`	vacío	Contraseña establecida para la interfaz HTTP/Lua de VLC
`VLC_HTTP_TIMEOUT_MS`	`5000`	Tiempo de espera de solicitud, de 100 a 120000 milisegundos
`MCP_TRANSPORT`	`stdio`	Transporte MCP: `stdio` o `http` local
`MCP_HTTP_PORT`	`3000`	Puerto para el modo HTTP local

Compilar desde el código fuente

Para trabajar en el código fuente del servidor en lugar de usar el paquete npm, clona y compila:

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

Ejecuta el servidor compilado con npm start. Espera a un cliente MCP en la entrada/salida estándar. El protocolo MCP usa stdout; el servidor no escribe registros de aplicación en stdout.

Publicación en el Registro MCP

Este repositorio incluye server.json y el campo mcpName correspondiente en package.json para el Registro MCP oficial. El Registro lista servidores MCP y es distinto de GitHub Marketplace, que publica GitHub Apps y Actions. Para enviar este servidor al Registro MCP, publica primero el paquete npm y el repositorio de GitHub, luego autentícate y publica con la CLI oficial:

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

El espacio de nombres del Registro en server.json y package.json es io.github.QuantumNovice/vlc-mcp. Crea el repositorio de GitHub en la URL configurada antes de publicar; la publicación en el registro requiere autenticación de GitHub para la cuenta que controla este espacio de nombres.

Notas de seguridad

Mantén la interfaz HTTP de VLC vinculada a localhost. La interfaz HTTP de VLC no proporciona cifrado de transporte, por lo que no debes exponerla directamente a una red no confiable. Si configuras una contraseña, usa una segura.
La herramienta vlc_add_media pasa su entrada a VLC. VLC puede abrir URLs de red o archivos locales accesibles para el proceso de VLC. Solo conecta clientes MCP confiables y concédeles acceso a medios que te sientas cómodo permitiendo que VLC abra.
El servidor solo hace solicitudes al VLC_BASE_URL configurado; no lo establezcas a un endpoint no confiable.

Licencia

MIT. Consulta LICENSE.