VLC MCP Server

VLC MCP 服务

一个用于使用 VLC media player 播放和控制影片的 MCP（Model Context Protocol）服务。 使用任意 MCP 客户端远程控制视频播放（例如 awesome-mcp-clients）

我在一台连接到投影仪的旧笔记本电脑上运行 signal-mcp-client。 这样，我就可以通过发送 signal 消息来播放影片。 下方截图展示了使用示例。

使用方法

此安装方法适用于运行 Ubuntu 或类似 Debian 的系统（例如 Raspberry Pi OS）的 Linux 系统。 稍作修改后，也应该能在其他系统上运行。 如果你成功在其他系统上运行，欢迎提交拉取请求。

1. 安装 VLC、mediainfo 和 uv。

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

2. 启动 VLC http 服务：

   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. 将服务添加到客户端的 MCP 配置文件中（例如 signal-mcp-client 或 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"
       }
   }
   

   或者克隆仓库并使用 uv 指定目录：

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

贡献

欢迎为此项目做出贡献。欢迎报告错误、提出想法或创建合并请求。

开发

克隆仓库并安装依赖：

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

测试

使用 mcp-client-for-testing，通过使用本地路径的 json 配置来测试服务的工具。

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

格式化与代码检查

代码使用 ruff 进行格式化和代码检查：

uv run ruff format
uv run ruff check --fix

使用 uv 构建

使用 uv 构建软件包：

uv build

发布新版本

要将软件包的新版本发布到 PyPI，请创建并推送新的 Git 标签：

1. 切换到 main 分支并获取当前版本：

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

2. 创建并推送新的 Git 标签：

   git tag v0.2.0
   git push origin v0.2.0
   

推送新标签后，GitHub Actions 工作流会自动构建软件包并将其发布到 PyPI。 Python 软件包的版本号将直接从 Git 标签中获取。

作为 Systemd 服务运行

若要确保 VLC HTTP 界面在 Linux 系统启动时自动运行，并在发生故障时自动重启，可以将其设置为 systemd 用户服务。 用户服务以你的特定用户帐户运行。

此设置假设你已完成设置步骤。

1. 启用用户保留功能，以便在注销后保持用户会话处于活动状态。

   sudo loginctl enable-linger $USER
   

2. 创建 Systemd 服务目录

   mkdir -p /home/$USER/.config/systemd/user/
   

3. 为 VLC HTTP 服务创建服务文件。 确保使用 apt 安装 vlc，而不是使用 snap；或者修改为 vlc 二进制文件的路径。

   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=8080'
   
   [Install]
   WantedBy=default.target
   EOF
   

4. 启用并启动服务

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

5. 检查服务状态和日志

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

许可证

此项目采用 MIT 许可证。详情请参阅 LICENSE 文件。