VLC MCP 服务器

这是一个使用 VLC 媒体播放器来播放和控制电影的 MCP（模型上下文协议）服务器。 您可以使用任何 MCP 客户端远程控制视频播放（例如 awesome-mcp-clients）。

我使用我的 signal-mcp-client，它运行在一个连接到投影仪的老笔记本电脑上。 这样，我可以通过发送信号消息来播放电影。 下面的截图展示了如何使用它的一个示例。

<p align="center"> <img src="https://raw.githubusercontent.com/piebro/vlc-mcp-server/main/assets/vlc_chat_screenshot.png" width="40%" style="padding: 1% 1% 1% 1%"> </p>

使用方法

此安装适用于运行 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 # 当在服务器上远程运行时需要设置
   vlc --extraintf=http --http-host=localhost --http-port=8081 --http-password=your_password
   

3. 将服务器添加到您的客户端的 MCP 配置文件中（例如 signal-mcp-client 或 awesome-m-mp-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. 切换到主分支并获取当前版本：

   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 文件。