vlc

The VLC MCP Server lets you control VLC media player playback remotely via the MCP protocol. It exposes controls to play, pause, stop, seek, and manage the current video, using an HTTP-based VLC interface under the hood. You can connect with any MCP client (for example, signal-mcp-client or awesome-mcp-clients) and issue tool calls such as show_video, play, pause, or seek, which will translate into VLC commands over its HTTP server. The server reads configuration from environment variables and exposes the VLC HTTP interface so you can securely control playback from your MCP client.

To use it, first ensure VLC is installed and the VLC HTTP interface is reachable (the server usually runs on localhost:8081 with a password you set). Then configure your MCP client with the provided JSON snippet, pointing the client at the uvx-based or uv-based server entry. Once connected, you can issue tool calls with parameters like a video title, language preferences, or specific seek positions, depending on the client’s capabilities and the server’s exposed tools.

Prerequisites:

• A Debian-based Linux system (Ubuntu, Raspberry Pi OS, etc.).
• VLC installed with HTTP interface support.
• Python 3 and uv (via uv/uva or uvx tooling) installed as described below.

Install and set up:

1. Install VLC and mediainfo (mediainfo is optional but often used for metadata): sudo apt-get update sudo apt-get install vlc mediainfo

2. Install uv (Python environment manager) per the server's guidance: curl -LsSf https://astral.sh/uv/install.sh | sh

3. Install project dependencies and prepare the environment (from the repository): git clone https://github.com/piebro/vlc-mcp-server.git cd vlc-mcp-server uv venv uv sync --extra dev uv run pre-commit install

4. Run the server in uvx mode (as described in the README): export ROOT_VIDEO_FOLDER=/path/to/your/videos export VLC_HTTP_HOST=localhost export VLC_HTTP_PORT=8081 export VLC_HTTP_PASSWORD=your_password uvx vlc-mcp-server

5. Optional: run the server with uv (directory mode) if you prefer: uv --directory /path/to/root/dir/ run vlc_mcp_player/main.py

6. Validate installation by testing with the included mcp-client-for-testing tool (from the repository): uvx mcp-client-for-testing --config '[ {"name": "vlc-mcp-server", ...}]' --tool_call '{"name": "show_video", "arguments": {"video_title": "Sample"}}'

Tips and common issues:

• Ensure the VLC HTTP interface is running and accessible with the configured host, port, and password. If VLC is behind a firewall or on a different host, adjust VLC_HTTP_HOST and the client’s target accordingly.
• The ROOT_VIDEO_FOLDER should point to your local library if you plan to use directory-based operation with uv. If you use the uvx approach, the server expects VLC to fetch and play media via its HTTP interface rather than a local file path.
• When running as a systemd service, you may need to adjust the ExecStart path to the exact VLC binary and ensure the user has the necessary permissions to access the display (DISPLAY variable).
• If you encounter issues connecting from an MCP client, verify that the MCP server’s config matches the client’s expected name and that the environment variables (VLC_HTTP_PASSWORD, etc.) are correctly exported.
• For testing, use the included mcp-client-for-testing tool to simulate client calls locally before deploying to production.
• If you switch from uvx to uv, keep the directory path consistent with your video library and use the appropriate run command as shown in the README.