{"id":27739287,"url":"https://github.com/piebro/vlc-mcp-server","last_synced_at":"2026-08-28T00:46:44.236Z","repository":{"id":287929177,"uuid":"966156588","full_name":"piebro/vlc-mcp-server","owner":"piebro","description":"An MCP (Model Context Protocol) Server to play and control movies using VLC.","archived":false,"fork":false,"pushed_at":"2025-06-11T15:34:46.000Z","size":516,"stargazers_count":13,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-07-25T14:45:54.208Z","etag":null,"topics":["mcp","mcp-server","vlc-media-player"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/piebro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-14T13:43:15.000Z","updated_at":"2026-07-15T14:03:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"7f98b4f6-d51d-41f0-b2e4-13367f783089","html_url":"https://github.com/piebro/vlc-mcp-server","commit_stats":null,"previous_names":["piebro/vlc-mcp-server"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/piebro/vlc-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piebro%2Fvlc-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piebro%2Fvlc-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piebro%2Fvlc-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piebro%2Fvlc-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piebro","download_url":"https://codeload.github.com/piebro/vlc-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piebro%2Fvlc-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36947905,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-27T02:00:07.166Z","response_time":96,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","vlc-media-player"],"created_at":"2025-04-28T15:02:25.795Z","updated_at":"2026-08-28T00:46:44.222Z","avatar_url":"https://github.com/piebro.png","language":"Python","funding_links":[],"categories":["Recently Updated","VLC web \u0026 lua extensions"],"sub_categories":["[Apr 28, 2025](/content/2025/04/28/README.md)"],"readme":"# VLC MCP Server\n\nAn MCP (Model Context Protocol) Server to play and control movies using the VLC media player.\nUse any MCP client to control play videos remotely (e.g. [awesome-mcp-clients](https://github.com/punkpeye/awesome-mcp-clients))\n\nI use my [signal-mcp-client](https://github.com/piebro/signal-mcp-client) running on an old laptop connected to my beamer.\nThis way I can play a movie by sending a signal message.\nAn example of how to use it is shown in the screenshot below.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/piebro/vlc-mcp-server/main/assets/vlc_chat_screenshot.png\" width=\"40%\" style=\"padding: 1% 1% 1% 1%\"\u003e\n\u003c/p\u003e\n\n## Usage\n\nThis installation is for Linux systems running Ubuntu or a similar Debian-based system like Raspberry Pi OS.\nWith a few modifications it should also work on other systems.\nFeel free to create a pull request if you get it working on another system.\n\n1. Install VLC, mediainfo and uv.\n    ```bash\n    sudo apt-get install vlc mediainfo\n    curl -LsSf https://astral.sh/uv/install.sh | sh\n    ```\n\n2. Start the VLC http server:\n    ```bash\n    export DISPLAY=:0 # needed when running it remotely on a server\n    vlc --extraintf=http --http-host=localhost --http-port=8081 --http-password=your_password\n    ```\n3. Add the server to the MCP config file of your client (like [signal-mcp-client](https://github.com/piebro/signal-mcp-client) or [awesome-mcp-clients](https://github.com/punkpeye/awesome-mcp-clients))\n    ```json\n    {\n        \"name\": \"vlc-mcp-server\",\n        \"command\": \"uvx\",\n        \"args\": [\n            \"vlc-mcp-server\"\n        ],\n        \"env\": {\n            \"ROOT_VIDEO_FOLDER\": \"path/to/your/video/folder\",\n            \"VLC_HTTP_HOST\": \"localhost\",\n            \"VLC_HTTP_PORT\": \"8081\",\n            \"VLC_HTTP_PASSWORD\": \"your_password\"\n        }\n    }\n    ```\n\n    or clone the repo and use `uv` with a directory:\n\n    ```json\n    {\n        \"name\": \"vlc-mcp-server\",\n        \"command\": \"uv\",\n        \"args\": [\n            \"--directory\",\n            \"path/to/root/dir/\",\n            \"run\",\n            \"vlc_mcp_player/main.py\"\n        ],\n        \"env\": {\n            \"the same as above\"\n        }\n    }\n    ```\n\n## Contributing\n\nContributions to this project are welcome. Feel free to report bugs, suggest ideas, or create merge requests.\n\n\n## Development\n\nClone repo and install dependencies:\n\n```bash\ngit clone https://github.com/piebro/vlc-mcp-server.git\nuv venv\nuv sync --extra dev\nuv run pre-commit install\n```\n\n### Testing\n\nUse [mcp-client-for-testing](https://github.com/piebro/mcp-client-for-testing) to test the tools of the server using the json config using the local path.\n\n```bash\nuvx mcp-client-for-testing \\\n    --config '\n    [\n        \"the json config from above\"\n    ]\n    ' \\\n    --client_log_level \"INFO\" \\\n\t--server_log_level \"INFO\" \\\n    --tool_call '{\"name\": \"show_video\", \"arguments\": {\"video_title\": \"David Lynch - Dune\", \"subtitle_language_code\": \"en\"}}'\n```\n\n### Formatting and Linting\n\nThe code is formatted and linted with ruff:\n\n```bash\nuv run ruff format\nuv run ruff check --fix\n```\n\n### Building with uv\n\nBuild the package using uv:\n\n```bash\nuv build\n```\n\n### Releasing a New Version\n\nTo release a new version of the package to PyPI, create and push a new Git tag:\n\n1. Checkout the main branch and get the current version:\n   ```bash\n   git checkout main\n   git pull origin main\n   git describe --tags\n   ```\n\n2. Create and push a new Git tag:\n   ```bash\n   git tag v0.2.0\n   git push origin v0.2.0\n   ```\n\nThe GitHub Actions workflow will automatically build and publish the package to PyPI when a new tag is pushed.\nThe python package version number will be derived directly from the Git tag.\n\n## Running as a Systemd Service\n\nTo 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.\nUser services run under your specific user account.\n\nThis setup assumes that you have completed the setup steps.\n\n1. Enable User Lingering to keep your user session active after logging out.\n    ```bash\n    sudo loginctl enable-linger $USER\n    ```\n\n2. Create Systemd Service Directory\n    ```bash\n    mkdir -p /home/$USER/.config/systemd/user/\n    ```\n3. Create Service File for VLC HTTP Server.\nMake sure vlc is installed using apt and not using snap or change the path to the vlc binary.\n    ```bash\n    cat \u003c\u003c EOF \u003e \"/home/$USER/.config/systemd/user/vlc-http.service\"\n    [Unit]\n    Description=VLC Media Player with HTTP Interface\n    After=network.target sound.target\n\n    [Service]\n    Restart=on-failure\n    RestartSec=30\n    SyslogIdentifier=vlc-http\n    Environment=\"DISPLAY=:0\"\n\n    ExecStart=/usr/bin/vlc --extraintf=http --http-host=localhost --http-port=8081 --http-password=your_password\n\n    ExecStop=/usr/bin/pkill -f '/usr/bin/vlc --extraintf=http --http-host=localhost --http-port=8080'\n\n    [Install]\n    WantedBy=default.target\n    EOF\n    ```\n\n4. Enable and Start the Services\n    ```bash\n    systemctl --user daemon-reload\n    systemctl --user enable vlc-http.service\n    systemctl --user start vlc-http.service\n    ```\n\n\n5. Check Service Status and Logs\n    ```bash\n    systemctl --user status vlc-http.service\n    journalctl --user -u vlc-http.service -f\n    ```\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiebro%2Fvlc-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiebro%2Fvlc-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiebro%2Fvlc-mcp-server/lists"}