Vlc MCP Server

🚀 VLC MCP Server

A Model Context Protocol (MCP) server that uses VLC media player to play and control movies. You can use any MCP client to remotely control video playback (e.g., awesome-mcp-clients).

I use the signal-mcp-client running on an old laptop and connect it to my projector. In this way, I can play movies by sending a signal message. The following shows an example of how to use it:

🚀 Quick Start

This installation is suitable for Linux systems running Ubuntu or similar Debian-based systems (e.g., Raspberry Pi OS). With appropriate modifications, it should also run on other systems. If you successfully run it on other systems, feel free to submit a pull request.

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 # This variable needs to be set when running on a remote server
   vlc --extraintf=http --http-host=localhost --http-port=8081 --http-password=your_password
   

3. Configure the MCP client to communicate with the VLC HTTP interface. For example, add the following to config.json:

   {
     "vlc": {
       "host": "localhost",
       "port": 8081,
       "password": "your_password"
     }
   }
   

4. Use the MCP client to control the VLC player. For example, send the following command to play media:

   mcpctl send vlc.play "media_url"
   

✨ Features

You can use any MCP client to remotely control video playback, which provides great convenience for playing and controlling movies.

📦 Installation

The installation steps are included in the "Quick Start" section above.

💻 Usage Examples

Basic Usage

The steps in the "Quick Start" section are the basic usage examples. You can follow those steps to install and start using the VLC MCP server.

Advanced Usage

You can customize the configuration according to your needs. For example, you can change the port number and password of the VLC HTTP server to enhance security.

🤝 Contribution Guidelines

Any contributions are welcome! If you find any issues, please submit an issue or a pull request on GitHub.

• Report Bugs: Please submit bugs on the Issues page.
• Feature Requests: You can also submit requests for new features on the Issues page.
• Code Contributions: Please fork the repository, make changes on your branch, and then create a pull request.

🛠️ Development Guidelines

1. Format Code: Use black to format Python code:

   black .
   

2. Build Documentation: Use sphinx-build to generate documentation:

   sphinx-build docs/ docs/_build/
   

3. Testing: Run unit tests to ensure the functionality is working properly.

⚙️ System Service Configuration

To automatically run the VLC HTTP server when the system starts, you can configure the systemd service as follows:

1. Create a file named vlc-http.service and add the following content:

   cat << EOF > "/home/$USER/.config/systemd/user/vlc-http.service"
   [Unit]
   Description=VLC Media Player with HTTP Interface
   After=network.target sound.target
   
   [Service]
   Restart=on-failure
   RestartSec=30
   SyslogIdentifier=vlc-http
   Environment="DISPLAY=:0"
   
   ExecStart=/usr/bin/vlc --extraintf=http --http-host=localhost --http-port=8081 --http-password=your_password
   
   ExecStop=/usr/bin/pkill -f '/usr/bin/vlc --extraintf=http --http-host=localhost --http-port=8081'
   
   [Install]
   WantedBy=default.target
   EOF
   

2. Enable and start the service:

   systemctl --user daemon-reload
   systemctl --user enable vlc-http.service
   systemctl --user start vlc-http.service
   

3. Check the service status and logs:

   systemctl --user status vlc-http.service
   journalctl --user -u vlc-http.service -f
   

📄 License

This project is open-source under the MIT license. For more details, please refer to the LICENSE file.