VLC MCP Server

An MCP server that lets AI clients inspect and control VLC Media Player using its built in HTTP interface. It uses MCP stdio by default for local clients, with an optional loopback-only Streamable HTTP mode for curl smoke checks and local HTTP clients.

What it can do

Requirements

• Node.js 20 or later
• VLC Media Player with the HTTP interface enabled
• An MCP client that can launch a local command over stdio

Quick setup with npm

1. Start VLC and enable its HTTP interface

1. Install and open VLC Media Player on the same computer where this MCP server will run.
2. Open Tools → Preferences. At the bottom left, change Show settings from Simple to All.
3. In the left panel, open Interface → Main interfaces and check Web.
4. Open Interface → Main interfaces → Lua and set the Lua HTTP password if your VLC setup requires one. VLC uses an empty username by default; this server also defaults both username and password to empty. Save the preferences and restart VLC after changing them.
5. Keep VLC's web interface on its default local address, http://127.0.0.1:8080. Do not expose the HTTP interface to the internet.

VLC preference labels can vary slightly by version. The setting is part of VLC's Lua HTTP interface. Leave the username blank unless your VLC server is configured with a username. If you set a Lua HTTP password, set VLC_HTTP_PASSWORD to the same value in the MCP client's environment.

2. Run the published MCP server

No clone or local build is needed. The published npm package can be run with npx; it downloads the package on first launch:

npx -y vlc-mcp-server

The command starts the MCP stdio server. Usually, put it in your AI client's MCP config so the client starts it automatically.

To install it globally instead, run npm install --global vlc-mcp-server; then use vlc-mcp-server as the MCP config command with an empty args array.

3. Add the server to your AI client

Add this entry under mcpServers in your AI client's configuration:

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

If the config already has an mcpServers object, add only the vlc property and keep the other server entries. Save the file and restart the client. If VLC has a Lua HTTP password, add VLC_HTTP_PASSWORD to env; leave VLC_HTTP_USERNAME empty unless you configured one.

4. Ask the AI to control VLC

Try these prompts:

• “Show the current VLC playback status.”
• “List the VLC playlist.”
• “Add a media file to VLC's playlist.”
• “Play the first item in the playlist.”
• “Pause VLC and set the volume to 120.”
• “Seek to 90 seconds.”

To play a specific item, first ask for the playlist, then pass the item's numeric ID to vlc_play. vlc_add_media accepts a local path or a URL that VLC supports. VLC needs permission to read the file or access the URL.

Connect from Claude Desktop

Claude Desktop can launch the package over stdio. Open %APPDATA%\Claude\claude_desktop_config.json (create it if needed) and add this under mcpServers:

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

If the file already contains other MCP servers, add only the vlc entry inside mcpServers. Save the file and restart Claude Desktop. Open a chat and ask Claude to list the VLC playlist. For current Claude Desktop extension options, see Anthropic's local MCP server guide.

Connect from OpenAI

OpenAI Agents SDK (local stdio)

For an application you run locally, install the OpenAI Agents SDK for JavaScript in that application with npm install @openai/agents. This example starts the published VLC package as a local process:

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

Set OPENAI_API_KEY before running the application. Set VLC_HTTP_PASSWORD only if you configured a Lua HTTP password in VLC. OpenAI's Agents SDK MCP guide documents local stdio and HTTP server connections.

ChatGPT or the OpenAI Responses API

ChatGPT and OpenAI hosted API requests cannot connect directly to this computer's 127.0.0.1 endpoint. To use this local VLC server from those hosted products, use OpenAI Secure MCP Tunnel. Create a tunnel in OpenAI Platform, run tunnel-client on this computer, and point it at this server's local stdio command or HTTP endpoint. Then add the tunnel in ChatGPT as a custom MCP server, or pass its tunnel_id in an OpenAI Responses API MCP tool. Tunnel setup and access depend on your OpenAI Platform and ChatGPT workspace permissions; see OpenAI's tunnel guide.

Connect from Hermes Agent

Hermes Agent supports local stdio MCP servers. Register the published npm package with Hermes' MCP CLI:

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

Start or restart Hermes with hermes chat, then ask it to show the VLC status. The server defaults to empty username and password. If you configured a Lua HTTP password, add it under mcp_servers.vlc.env.VLC_HTTP_PASSWORD in Hermes config. Hermes MCP setup and config options are documented in the Hermes MCP guide.

Use Ollama models with an MCP host

Ollama runs the model; configure the MCP server in the agent or client that connects to that model. Ollama's /api/chat tool calling takes function definitions from the client, so it does not use this server's MCP config directly. Use an MCP-capable host such as Hermes Agent or OpenClaw, then select Ollama as that host's model provider. Ollama's ollama launch can set up supported agent integrations:

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

Then configure the vlc MCP server in Hermes or OpenClaw using the section above. Use a model with tool calling support; ollama show qwen3 displays the model capabilities. For direct application code, your app must act as the MCP client and forward discovered MCP tools to Ollama's chat API; see Ollama tool support.

Connect from llama.cpp

Recent llama-server builds support MCP servers over stdio (the feature is marked experimental). Save this Cursor-style MCP config as vlc-mcp-servers.json:

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

Append this option to the command you already use to start llama-server.exe from the directory containing the config file:

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

If VLC has a Lua HTTP password, add VLC_HTTP_PASSWORD to the config's env. The MCP tools are then registered alongside the model server's other tools. See the llama.cpp MCP server documentation.

Connect from OpenClaw

OpenClaw supports local stdio MCP servers. Add the published package and probe its tools:

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

The probe should list the VLC tools. To set a VLC password or other environment values, edit the vlc server in OpenClaw's Settings → MCP page or its mcp.servers config. Keep VLC_HTTP_PASSWORD empty unless you set a Lua HTTP password in VLC.

OpenClaw's MCP guide documents the UI, CLI, and config options.

Test the MCP endpoint with curl

The MCP endpoint uses stdio by default. To test with curl, start the published package in its optional local HTTP mode:

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

Leave that window running. In a second PowerShell window, initialize an MCP connection:

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

List the MCP tools:

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

Call VLC status (VLC must be running and its HTTP interface enabled):

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

The responses may be returned as Server-Sent Events (event: message followed by a JSON data: line). This HTTP mode is bound to 127.0.0.1; it is for local checks and local clients. Stop it with Ctrl+C.

5. Troubleshoot a connection

• Connection refused or timeout: Make sure VLC is open, the Web interface is enabled, and VLC_BASE_URL points to the computer running VLC.
• 401 Unauthorized: Leave VLC_HTTP_USERNAME empty. If you set a Lua HTTP password in VLC, copy it into VLC_HTTP_PASSWORD and restart the MCP client. If you did not set one, keep both values empty.
• Media does not play: Confirm VLC can open the same file or URL directly. Check that the path exists on the computer running VLC.

Environment variables

Build from source

To work on the server source instead of using the npm package, clone and build it:

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

Run the built server with npm start. It waits for an MCP client on standard input/output. The MCP protocol uses stdout; the server does not write application logs to stdout.

MCP Registry publishing

This repository includes server.json and the matching mcpName field in package.json for the official MCP Registry. The Registry lists MCP servers and is distinct from GitHub Marketplace, which publishes GitHub Apps and Actions. To submit this server to the MCP Registry, publish the npm package and GitHub repository first, then authenticate and publish with the official CLI:

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

The Registry namespace in server.json and package.json is io.github.QuantumNovice/vlc-mcp. Create the GitHub repository at the configured URL before publishing; registry publication requires GitHub authentication for the account that controls this namespace.

Security notes

• Keep VLC's HTTP interface bound to localhost. VLC's HTTP interface does not provide transport encryption, so do not expose it directly to an untrusted network. If you configure a password, use a strong one.
• The vlc_add_media tool passes its input to VLC. VLC may open network URLs or local files accessible to the VLC process. Only connect trusted MCP clients and grant them access to media you are comfortable allowing VLC to open.
• The server only makes requests to the configured VLC_BASE_URL; do not set it to an untrusted endpoint.

License

MIT. See LICENSE.