VLC MCP Server

An MCP (Model Context Protocol) Server to play and control movies using the VLC media player. Use any MCP client to control play videos remotely (e.g. awesome-mcp-clients)

I use my signal-mcp-client running on an old laptop connected to my beamer. This way I can play a movie by sending a signal message. An example of how to use it is shown in the screenshot below.

Usage

This installation is for Linux systems running Ubuntu or a similar Debian-based system like Raspberry Pi OS. With a few modifications it should also work on other systems. Feel free to create a pull request if you get it working on another system.

1. Install VLC, mediainfo and uv.

   sudo apt-get install vlc mediainfo
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Start the VLC http server:

   export DISPLAY=:0 # needed when running it remotely on a server
   vlc --extraintf=http --http-host=localhost --http-port=8081 --http-password=your_password
   

3. Add the server to the MCP config file of your client (like signal-mcp-client or awesome-mcp-clients)

   {
       "name": "vlc-mcp-server",
       "command": "uvx",
       "args": [
           "vlc-mcp-server"
       ],
       "env": {
           "ROOT_VIDEO_FOLDER": "path/to/your/video/folder",
           "VLC_HTTP_HOST": "localhost",
           "VLC_HTTP_PORT": "8081",
           "VLC_HTTP_PASSWORD": "your_password"
       }
   }
   

   or clone the repo and use uv with a directory:

   {
       "name": "vlc-mcp-server",
       "command": "uv",
       "args": [
           "--directory",
           "path/to/root/dir/",
           "run",
           "vlc_mcp_player/main.py"
       ],
       "env": {
           "the same as above"
       }
   }
   

Contributing

Contributions to this project are welcome. Feel free to report bugs, suggest ideas, or create merge requests.

Development

Clone repo and install dependencies:

git clone https://github.com/piebro/vlc-mcp-server.git
uv venv
uv sync --extra dev
uv run pre-commit install

Testing

Use mcp-client-for-testing to test the tools of the server using the json config using the local path.

uvx mcp-client-for-testing \
    --config '
    [
        "the json config from above"
    ]
    ' \
    --client_log_level "INFO" \
	--server_log_level "INFO" \
    --tool_call '{"name": "show_video", "arguments": {"video_title": "David Lynch - Dune", "subtitle_language_code": "en"}}'

Formatting and Linting

The code is formatted and linted with ruff:

uv run ruff format
uv run ruff check --fix

Building with uv

Build the package using uv:

uv build

Releasing a New Version

To release a new version of the package to PyPI, create and push a new Git tag:

1. Checkout the main branch and get the current version:

   git checkout main
   git pull origin main
   git describe --tags
   

2. Create and push a new Git tag:

   git tag v0.2.0
   git push origin v0.2.0
   

The GitHub Actions workflow will automatically build and publish the package to PyPI when a new tag is pushed. The python package version number will be derived directly from the Git tag.

Running as a Systemd Service

To ensure the VLC HTTP interface runs automatically on boot and restarts if it fails (on Linux systems), you can set it up as a systemd user service. User services run under your specific user account.

This setup assumes that you have completed the setup ste

... View full README on GitHub