VLC MCP

Servidor VLC MCP: controle o VLC Media Player com Claude, ChatGPT e Ollama

vlc-mcp é um servidor Model Context Protocol (MCP) e plugin do Claude Code que permite que clientes de IA inspecionem e controlem o VLC Media Player usando sua interface HTTP integrada. Ele usa MCP stdio por padrão para clientes locais, com um modo opcional Streamable HTTP somente loopback para verificações rápidas com curl e clientes HTTP locais.

O ícone do cone do VLC é de VideoLAN. VLC e o logotipo do cone são marcas registradas da VideoLAN; este projeto independente não é afiliado à VideoLAN.

O que ele pode fazer

Ferramenta	Finalidade
vlc_get_status	Ler estado de reprodução, mídia, tempo decorrido, duração e volume
vlc_list_playlist	Listar itens de mídia e seus IDs de playlist do VLC
vlc_play	Retomar a reprodução ou reproduzir um item da playlist por ID
vlc_pause	Alternar o estado de pausa da reprodução
vlc_stop	Parar a reprodução
vlc_next / vlc_previous	Alterar item da playlist
vlc_set_volume	Definir volume de 0 a 512
vlc_seek	Avançar para uma posição em segundos
vlc_add_media	Adicionar um caminho de mídia local ou uma URL de mídia suportada pelo VLC à playlist

Requisitos

• Node.js 20 ou posterior
• VLC Media Player com a interface HTTP habilitada
• Um cliente MCP que possa iniciar um comando local via stdio

Configuração rápida com npm

1. Inicie o VLC e habilite sua interface HTTP

1. Instale e abra o VLC Media Player no mesmo computador onde este servidor MCP será executado.
2. Abra Ferramentas → Preferências. No canto inferior esquerdo, altere Mostrar configurações de Simples para Todos.
3. No painel esquerdo, abra Interface → Interfaces principais e marque Web.
4. Abra Interface → Interfaces principais → Lua e defina a senha Lua HTTP se sua configuração do VLC exigir uma. O VLC usa um nome de usuário vazio por padrão; este servidor também usa nome de usuário e senha vazios por padrão. Salve as preferências e reinicie o VLC após alterá-las.
5. Mantenha a interface web do VLC em seu endereço local padrão, http://127.0.0.1:8080. Não exponha a interface HTTP à internet.

Os rótulos das preferências do VLC podem variar ligeiramente conforme a versão. A configuração faz parte da interface Lua HTTP do VLC. Deixe o nome de usuário em branco, a menos que seu servidor VLC esteja configurado com um nome de usuário. Se você definir uma senha Lua HTTP, defina VLC_HTTP_PASSWORD com o mesmo valor no ambiente do cliente MCP.

2. Execute o servidor MCP publicado

Não é necessário clonar ou compilar localmente. O pacote npm publicado pode ser executado com npx; ele baixa o pacote no primeiro início:

npx -y vlc-mcp-server

O comando inicia o servidor MCP stdio. Normalmente, coloque-o na configuração MCP do seu cliente de IA para que o cliente o inicie automaticamente.

Para instalá-lo globalmente, execute npm install --global vlc-mcp-server; depois use vlc-mcp-server como command da configuração MCP com um array args vazio.

3. Adicione o servidor ao seu cliente de IA

Adicione esta entrada em mcpServers na configuração do seu cliente de IA:

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

Se a configuração já tiver um objeto mcpServers, adicione apenas a propriedade vlc e mantenha as outras entradas de servidor. Salve o arquivo e reinicie o cliente. Se o VLC tiver uma senha Lua HTTP, adicione VLC_HTTP_PASSWORD a env; deixe VLC_HTTP_USERNAME vazio, a menos que você tenha configurado um.

4. Peça à IA para controlar o VLC

Experimente estes prompts:

• "Mostre o status de reprodução atual do VLC."
• "Liste a playlist do VLC."
• "Adicione um arquivo de mídia à playlist do VLC."
• "Reproduza o primeiro item da playlist."
• "Pause o VLC e defina o volume para 120."
• "Avançe para 90 segundos."

Para reproduzir um item específico, primeiro peça a playlist e depois passe o ID numérico do item para vlc_play. vlc_add_media aceita um caminho local ou uma URL suportada pelo VLC. O VLC precisa de permissão para ler o arquivo ou acessar a URL.

Instalar como plugin do Claude Code

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

Conectar do Claude Desktop

O Claude Desktop pode iniciar o pacote via stdio. Abra %APPDATA%\Claude\claude_desktop_config.json (crie-o se necessário) e adicione isto em mcpServers:

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

Se o arquivo já contiver outros servidores MCP, adicione apenas a entrada vlc dentro de mcpServers. Salve o arquivo e reinicie o Claude Desktop. Abra um chat e peça ao Claude para listar a playlist do VLC. Para opções atuais de extensão do Claude Desktop, consulte o guia de servidores MCP locais da Anthropic.

Conectar do OpenAI

OpenAI Agents SDK (stdio local)

Para um aplicativo executado localmente, instale o OpenAI Agents SDK para JavaScript nesse aplicativo com npm install @openai/agents. Este exemplo inicia o pacote VLC publicado como um processo 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();
}

Defina OPENAI_API_KEY antes de executar o aplicativo. Defina VLC_HTTP_PASSWORD somente se você configurou uma senha Lua HTTP no VLC. O guia MCP do Agents SDK da OpenAI documenta conexões de servidor stdio local e HTTP.

ChatGPT ou a API Responses da OpenAI

O ChatGPT e as solicitações hospedadas da API da OpenAI não podem se conectar diretamente ao endpoint 127.0.0.1 deste computador. Para usar este servidor VLC local desses produtos hospedados, use o OpenAI Secure MCP Tunnel. Crie um túnel no OpenAI Platform, execute tunnel-client neste computador e aponte-o para o comando stdio local ou endpoint HTTP deste servidor. Depois, adicione o túnel no ChatGPT como um servidor MCP personalizado ou passe seu tunnel_id em uma ferramenta MCP da API Responses da OpenAI. A configuração e o acesso ao túnel dependem das permissões do seu OpenAI Platform e do workspace do ChatGPT; consulte o guia de túnel da OpenAI.

Conectar do Hermes Agent

O Hermes Agent suporta servidores MCP stdio locais. Registre o pacote npm publicado com a CLI MCP do Hermes:

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

Inicie ou reinicie o Hermes com hermes chat e peça para mostrar o status do VLC. O servidor usa nome de usuário e senha vazios por padrão. Se você configurou uma senha Lua HTTP, adicione-a em mcp_servers.vlc.env.VLC_HTTP_PASSWORD na configuração do Hermes. A configuração e as opções do MCP do Hermes estão documentadas no guia MCP do Hermes.

Usar modelos Ollama com um host MCP

O Ollama executa o modelo; configure o servidor MCP no agente ou cliente que se conecta a esse modelo. A chamada de ferramentas /api/chat do Ollama recebe definições de funções do cliente, portanto não usa a configuração MCP deste servidor diretamente. Use um host compatível com MCP, como Hermes Agent ou OpenClaw, e selecione Ollama como provedor de modelo desse host. O ollama launch do Ollama pode configurar integrações de agentes suportadas:

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

Depois, configure o servidor MCP vlc no Hermes ou OpenClaw usando a seção acima. Use um modelo com suporte a chamada de ferramentas; ollama show qwen3 exibe as capacidades do modelo. Para código de aplicativo direto, seu aplicativo deve atuar como cliente MCP e encaminhar as ferramentas MCP descobertas para a API de chat do Ollama; consulte suporte a ferramentas do Ollama.

Conectar do llama.cpp

Builds recentes de llama-server suportam servidores MCP via stdio (o recurso está marcado como experimental). Salve esta configuração MCP no 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"
      }
    }
  }
}

Anexe esta opção ao comando que você já usa para iniciar llama-server.exe a partir do diretório que contém o arquivo de configuração:

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

Se o VLC tiver uma senha Lua HTTP, adicione VLC_HTTP_PASSWORD ao env da configuração. As ferramentas MCP são então registradas junto com as outras ferramentas do servidor de modelo. Consulte a documentação do servidor MCP do llama.cpp.

Conectar do OpenClaw

O OpenClaw suporta servidores MCP stdio locais. Adicione o pacote publicado e teste suas ferramentas:

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

O teste deve listar as ferramentas do VLC. Para definir uma senha do VLC ou outros valores de ambiente, edite o servidor vlc na página Configurações → MCP do OpenClaw ou em sua configuração mcp.servers. Mantenha VLC_HTTP_PASSWORD vazio, a menos que você tenha definido uma senha Lua HTTP no VLC.

O guia MCP do OpenClaw documenta a interface, a CLI e as opções de configuração.

Testar o endpoint MCP com curl

O endpoint MCP usa stdio por padrão. Para testar com curl, inicie o pacote publicado em seu modo HTTP local opcional:

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

Deixe essa janela aberta. Em uma segunda janela do PowerShell, inicialize uma conexão 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"}}}'

Liste as ferramentas 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"}'

Chame o status do VLC (o VLC deve estar em execução e sua interface 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":{}}}'

As respostas podem ser retornadas como Server-Sent Events (event: message seguido por uma linha JSON data:). Este modo HTTP está vinculado a 127.0.0.1; é para verificações locais e clientes locais. Pare-o com Ctrl+C.

5. Solucionar problemas de conexão

• Conexão recusada ou tempo limite: Verifique se o VLC está aberto, se a interface Web está habilitada e se VLC_BASE_URL aponta para o computador que executa o VLC.
• 401 Não autorizado: Deixe VLC_HTTP_USERNAME vazio. Se você definiu uma senha Lua HTTP no VLC, copie-a para VLC_HTTP_PASSWORD e reinicie o cliente MCP. Se você não definiu uma, mantenha ambos os valores vazios.
• A mídia não reproduz: Confirme se o VLC pode abrir o mesmo arquivo ou URL diretamente. Verifique se o caminho existe no computador que executa o VLC.

Variáveis de ambiente

Variável	Padrão	Descrição
VLC_BASE_URL	http://127.0.0.1:8080	URL da interface HTTP do VLC
VLC_HTTP_USERNAME	vazio	Nome de usuário para a interface HTTP/Lua do VLC
VLC_HTTP_PASSWORD	vazio	Senha definida para a interface HTTP/Lua do VLC
VLC_HTTP_TIMEOUT_MS	5000	Tempo limite de solicitação, de 100 a 120000 milissegundos
MCP_TRANSPORT	stdio	Transporte MCP: stdio ou http local
MCP_HTTP_PORT	3000	Porta para o modo HTTP local

Compilar a partir do código-fonte

Para trabalhar no código-fonte do servidor em vez de usar o pacote npm, clone e compile:

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

Execute o servidor compilado com npm start. Ele aguarda um cliente MCP na entrada/saída padrão. O protocolo MCP usa stdout; o servidor não grava logs de aplicativo em stdout.

Publicação no Registro MCP

Este repositório inclui server.json e o campo mcpName correspondente em package.json para o Registro MCP oficial. O Registro lista servidores MCP e é distinto do GitHub Marketplace, que publica GitHub Apps e Actions. Para enviar este servidor ao Registro MCP, publique primeiro o pacote npm e o repositório GitHub, depois autentique e publique com a CLI oficial:

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

O namespace do Registro em server.json e package.json é io.github.QuantumNovice/vlc-mcp. Crie o repositório GitHub na URL configurada antes de publicar; a publicação no registro exige autenticação GitHub para a conta que controla este namespace.

Notas de segurança

• Mantenha a interface HTTP do VLC vinculada a localhost. A interface HTTP do VLC não fornece criptografia de transporte, portanto não a exponha diretamente a uma rede não confiável. Se você configurar uma senha, use uma forte.
• A ferramenta vlc_add_media passa sua entrada para o VLC. O VLC pode abrir URLs de rede ou arquivos locais acessíveis ao processo do VLC. Conecte apenas clientes MCP confiáveis e conceda a eles acesso a mídias que você se sinta confortável em permitir que o VLC abra.
• O servidor só faz solicitações ao VLC_BASE_URL configurado; não o defina para um endpoint não confiável.

Licença

MIT. Consulte LICENSE.