How do I use vlc-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vlc-mcp Play Arrival with English subtitles and set volume to 60%" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

vlc-mcp

by jaseonline

Overview Schema Source Related Servers Discussions Admin

Python

Local

vlc-mcp

vlc-mcp is a Model Context Protocol (MCP) server that lets an AI assistant such as Claude find, play and control videos in VLC. It talks to VLC's built-in HTTP interface and runs locally over stdio.

Last updated: 2026-11-12

Features

Library: list every .mkv and .mp4 under your video folder, or browse folders through VLC's own file browser.
Playback: play a video full screen with a chosen embedded subtitle language. Also play, pause, stop, skip, seek, change speed, set the aspect ratio and fix audio or subtitle sync.
Volume: set, read or step the volume from 0 to 200%.
Tracks: list and switch titles, chapters, audio, video and subtitle tracks, and load external subtitle files.
Playlist: add, play, clear and sort items, and toggle shuffle, loop and repeat.
Equalizer: turn it on or off, pick a preset, and set the preamp and each of the 10 bands.
Extras: fetch the cover art for the current item, and run raw VLM (VideoLAN Manager) commands.

Related MCP server: Plex Assistant MCP

Prerequisites

Requirement	Why
VLC with the web (HTTP) interface on	Every tool sends its commands through it
uv	Installs and runs the server
Python 3.10+	Runtime (uv can install it for you)
MediaInfo CLI on `PATH`	`show_video` reads it to find the embedded subtitle tracks

Turn on VLC's HTTP interface

From the command line:

vlc --extraintf http --http-host localhost --http-port 8085 --http-password "choose-a-password"

Or in the VLC GUI:

Tools → Preferences, then set Show settings to All.
Interface → Main interfaces: tick Web.
Interface → Main interfaces → Lua: set a Lua HTTP password.
Restart VLC. The port defaults to 8080, so either pass --http-port 8085 or set VLC_HTTP_PORT=8080.

To check it works, open http://localhost:8085, leave the username blank and enter the password.

Installation

Run the server straight from GitHub with uv:

uvx --from git+https://github.com/jaseonline/vlc-mcp vlc-mcp

Or clone it for local use or development:

git clone https://github.com/jaseonline/vlc-mcp.git
cd vlc-mcp
uv sync
uv run vlc-mcp

Configuration

The server is configured through environment variables. Set them in your MCP client's config. It exits at start-up if ROOT_VIDEO_FOLDER is missing.

Variable	Required	Description
`ROOT_VIDEO_FOLDER`	Yes	Folder that holds your videos. Tool paths are relative to it.
`VLC_HTTP_PASSWORD`	Yes, in practice	Password for VLC's HTTP interface. The fallback `your_password` will fail VLC's login.
`VLC_HTTP_HOST`	No	Host where VLC is listening. Defaults to `localhost`.
`VLC_HTTP_PORT`	No	Port VLC's HTTP interface listens on. Defaults to `8085`.

Claude Desktop

Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "vlc": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/jaseonline/vlc-mcp", "vlc-mcp"],
      "env": {
        "ROOT_VIDEO_FOLDER": "D:\\Videos",
        "VLC_HTTP_PASSWORD": "choose-a-password"
      }
    }
  }
}

Claude Code

claude mcp add vlc \
  -e ROOT_VIDEO_FOLDER="D:\Videos" \
  -e VLC_HTTP_PASSWORD="choose-a-password" \
  -- uvx --from git+https://github.com/jaseonline/vlc-mcp vlc-mcp

Usage

Once the server is connected, ask for what you want in plain language. For example:

"What films have I got?" "Play Arrival with English subtitles." "Skip back 30 seconds and turn it down to 60%." "The audio's out of sync. Delay it by half a second." "Queue the next three episodes and turn on shuffle."

Tools

Area	Tool	What it does
Library	`get_available_videos`	Lists every `.mkv` and `.mp4` under `ROOT_VIDEO_FOLDER`
	`browse_folder`	Lists the files and folders VLC can see in a folder
	`show_video`	Plays a video full screen, with an optional subtitle language code such as `eng`
Status	`get_status`	Shows the state, position, file, rate, playlist modes and full-screen state
Transport	`vlc_control`	Runs `play`, `pause`, `toggle`, `stop`, `next`, `previous` or `fullscreen`
	`seek`	Jumps to a time or percentage, absolute or relative: `30s`, `-10s`, `+1h:2m:3s`, `50%`
	`set_playback_rate`	Sets the speed (`1.0` is normal)
	`set_aspect_ratio`	Sets the aspect ratio: `16:9`, `4:3`, `235:100` and others, or `default` to reset
	`set_sync_delay`	Sets the audio or subtitle delay in seconds
Volume	`set_volume`, `get_volume`, `adjust_volume`	Sets, reads or steps the volume, 0 to 200%
Tracks	`get_tracks`	Lists the streams, titles and chapters of the current item
	`select_track`	Switches the title, chapter, audio, video or subtitle track (`-1` turns subtitles off)
	`add_subtitle`	Loads an external subtitle file such as `.srt`
Playlist	`get_playlist`	Lists the items with their ids and marks the current one
	`enqueue_video`	Adds a video to the end without playing it
	`play_playlist_item`	Plays an item by its id
	`remove_playlist_item`	Removes an item (VLC marks this as unsupported, so it may not work)
	`clear_playlist`	Empties the playlist
	`sort_playlist`	Sorts by `id`, `name`, `author`, `random` or `track_number`, optionally in reverse
	`toggle_playlist_mode`	Turns `random`, `loop` or `repeat` on or off
Equalizer	`get_equalizer`	Shows the preamp, the band gains and the presets
	`set_equalizer`	Turns it on or off, picks a preset, and sets the preamp or one band (−20 to 20 dB)
Extras	`get_album_art`	Returns the cover image for the current item or a playlist item
	`vlm`	Runs a raw VLM command, or lists the VLM elements when no command is given

show_video sets the volume to 100%, starts playback, waits about four seconds and then switches to full screen.

Development

uv sync --extra dev        # install ruff and pre-commit
uv run pre-commit install  # run the hooks on every commit
uv run ruff check .        # lint
uv run ruff format .       # format
uv run pytest              # tests (VLC is mocked, so none needs to be running)

To try the tools interactively without an AI client, use the MCP Inspector:

npx @modelcontextprotocol/inspector uv run vlc-mcp

Set ROOT_VIDEO_FOLDER and VLC_HTTP_PASSWORD in your shell first.

Logs go to stderr, because stdout carries the MCP protocol stream.

Security

Keep VLC's HTTP interface on localhost. Its only protection is a password sent with HTTP Basic auth over plain HTTP.
vlm passes commands straight to VLC, and paths can point outside ROOT_VIDEO_FOLDER when given as absolute paths. Only connect the server to clients you trust.

Report vulnerabilities privately: see SECURITY.md.

Project layout

Path	Contents
`src/vlc_mcp/main.py`	The MCP server and all its tools
`tests/`	pytest suite, with VLC's HTTP interface mocked
`docs/requests.txt`	Reference for VLC's HTTP interface commands
`.github/workflows/`	CI: tests and lockfile check, Super-Linter, GitGuardian, Claude review

Contributing

See CONTRIBUTING.md.

Licence

MIT

Available Tools

26 tools

add_subtitleA

Load an external subtitle file into the currently playing video.

Args: subtitle_path: Path relative to the video folder (or an absolute path) of a subtitle file such as .srt

Inputs: subtitle_path (required). Returns: result

adjust_volumeB

Increase or decrease the volume by a specified percentage.

Args: change: An integer representing the percentage to change the volume by. Positive values increase volume, negative values decrease it.

Inputs: change (required). Returns: result

browse_folderB

List the files and folders VLC sees in a folder, via VLC's own file browser.

Args: folder: Path relative to the video folder (empty for the video folder itself), or an absolute path

Inputs: folder. Returns: result

clear_playlistA

Remove every item from the playlist.

Inputs: no named parameters. Returns: result

enqueue_videoA

Add a video to the end of the playlist without starting it.

Args: video_path: Path relative to the video folder, as returned by get_available_videos

Inputs: video_path (required). Returns: result

get_album_artB

Get the album art / cover image for the current item, or for a playlist item id from get_playlist.

Inputs: item_id.

get_available_videosB

Get all available videos with their path.

Inputs: no named parameters. Returns: result

get_equalizerA

Show the equalizer state: preamp, band gains and the available presets.

Inputs: no named parameters. Returns: result

get_playlistA

List the items in the VLC playlist with their ids. The current item is marked with *.

Inputs: no named parameters. Returns: result

get_statusB

Get the current status of VLC playback.

Inputs: no named parameters. Returns: result

get_tracksA

List the streams (audio, video, subtitle) of the current item, plus titles and chapters.

Use the stream numbers shown here with select_track.

Inputs: no named parameters. Returns: result

get_volumeA

Get the current volume level of VLC (as a percentage).

Inputs: no named parameters. Returns: result

play_playlist_itemA

Play a playlist item by its id (from get_playlist). If item_id is omitted, plays the last active item.

Inputs: item_id. Returns: result

remove_playlist_itemB

Remove an item from the playlist by its id. VLC marks this command as unsupported, so it may not work.

Inputs: item_id (required). Returns: result

seekA

Seek to a specific position in the video. + or - seek relative to the current position and otherwise absolute.

Allowed values are of the form: [+ or -][:][:][] or [+ or -]% Examples: -10s -> seek 10 seconds backward +1h:2m:3s -> seek 1 hour, 2 minutes and 3 seconds forward 30s -> seek to the 30th second 50% -> seek to the middle -10% -> seek 10% back

Inputs: value (required). Returns: result

select_trackA

Select a title, chapter, audio track, video track or subtitle track.

Args: kind: One of title, chapter, audio, video, subtitle track_id: The stream number from get_tracks (or the title/chapter number). Use -1 for subtitle to disable it.

Inputs: kind (required), track_id (required). Returns: result

set_aspect_ratioB

Set the video aspect ratio.

Args: ratio: One of 1:1, 4:3, 5:4, 16:9, 16:10, 221:100, 235:100, 239:100, or "default" to reset.

Inputs: ratio (required). Returns: result

set_equalizerA

Change the equalizer. Only the arguments you pass are applied.

Args: enabled: True to enable, False to disable the equalizer preset_id: Preset id from get_equalizer preamp_db: Preamp level, -20 to 20 dB band: Band 0-9 (0: 60 Hz, 1: 170 Hz, 2: 310 Hz, 3: 600 Hz, 4: 1 kHz, 5: 3 kHz, 6: 6 kHz, 7: 12 kHz, 8: 14 kHz, 9: 16 kHz). Requires gain_db. gain_db: Gain for the band, -20 to 20 dB

Inputs: band, enabled, gain_db, preamp_db, +1 more. Returns: result

set_playback_rateB

Set the playback speed. 1.0 is normal speed, 2.0 is double, 0.5 is half. Must be greater than 0.

Inputs: rate (required). Returns: result

set_sync_delayA

Set the audio or subtitle delay to fix out-of-sync playback.

Args: stream: "audio" or "subtitle" seconds: Delay in seconds (can be negative or fractional, e.g. -0.5). 0 resets it.

Inputs: stream (required), seconds (required). Returns: result

set_volumeB

Set the volume level of VLC (0-200, where 100 is normal volume).

Args: volume_level: An integer between 0 and 200 representing the volume percentage

Inputs: volume_level (required). Returns: result

show_videoC

Show the video using the the video path and the subtitle language code. If the subtitle language code is an empty string, the video will play with no subtitle.

Inputs: video_path (required), subtitle_language_code. Returns: result

sort_playlistB

Sort the playlist.

Args: mode: One of id, name, author, random, track_number reverse: True to sort in reverse order

Inputs: mode (required), reverse. Returns: result

toggle_playlist_modeA

Toggle a playlist mode on or off and report its new state.

Args: mode: "random" (shuffle), "loop" (repeat whole playlist) or "repeat" (repeat current item)

Inputs: mode (required). Returns: result

vlc_controlA

Control VLC playback.

Actions: play - resume playback if paused (does nothing if already playing) pause - pause playback (does nothing if already paused) toggle - toggle pause; if stopped, plays the current or first playlist item stop - stop playback next - jump to the next playlist item previous - jump to the previous playlist item fullscreen - toggle fullscreen

Inputs: action (required). Returns: result

vlmA

Run a VLM (VideoLAN Manager) command, or list VLM elements when command is empty.

Args: command: A VLM command such as "show", "new mybroadcast broadcast enabled", "control mybroadcast play". Leave empty to list all VLM elements. Returns VLC's raw XML response.

Inputs: command. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-11-12 19:55 across 26 tools

Disambiguation4/5

Most tools target a clearly distinct resource or action (volume, tracks, equalizer, playlist, subtitles, seeking), so an agent can pick correctly. There is mild overlap around playback start paths—show_video vs enqueue_video + play_playlist_item vs vlc_control(play/toggle)—and vlm is a catch-all escape hatch that partially duplicates other controls.

Naming Consistency4/5

The set is overwhelmingly consistent snake_case verb_noun (get_volume, set_equalizer, play_playlist_item, toggle_playlist_mode, clear_playlist). A few outliers break the pattern: bare 'vlm', bare 'seek', and noun-first 'vlc_control', though they remain readable.

Tool Count3/5

26 tools is at/just over the heavy end for a media-player controller. Each maps to a real VLC capability, but the surface could be trimmed (e.g. vlm overlaps other tools, volume get/set/adjust could collapse), making it borderline rather than well-scoped.

Completeness4/5

Coverage is broad: playback, volume, tracks/titles/chapters, subtitles, playlist management, equalizer, aspect ratio, A/V sync, seek, rate, file browsing, album art, and VLM. Only minor gaps remain (e.g. screenshot/snapshot, audio output device selection, recording), which agents can mostly work around via vlm.

Maintenance

ActivityMaintained

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

mytesla.io
io.mytesla
Control your Tesla from your AI assistant - climate, charging, access, and security.
Home Automation & IoT Travel & Transportation
2
https://mcp.mytesla.io/mcp
DNS-DATA RemoteDeprecated
com.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
File Systems Command Line OS Automation
11
https://mcp.dns-data.com/mcp
PC Remote Commander
io.github.pcremotecommander
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
File Systems Command Line Browser Automation
11
https://pc-remote-commander.pcremotecommander.workers.dev/mcp
TVWizard
ai.djwizard
Control Android TV from any AI. 38 MCP tools: playback, recap, recommend, smart-home, schedules.
Home Automation & IoT Entertainment & Media
2
https://tv.djwizard.ai/mcp/

Related MCP Servers

Spotify MCP Server
Entertainment & Media App Automation
makesh-kumar
F
license
B
quality
D
maintenance
Enables AI assistants to control Spotify playback, search for music, manage playlists, and interact with your Spotify library through natural language commands.
Updated 8 months ago (2026-03-23 21:47 UTC)
19
-
Plex Assistant MCP
Entertainment & Media Home Automation & IoT
axelterrier
A
license
Not graded
quality
D
maintenance
Enables users to manage and control their Plex media library through natural language commands in MCP-compatible AI clients. It supports searching content, managing playlists, tracking library statistics, and monitoring live viewing sessions.
Updated a year ago (2025-10-27 09:34 UTC)
MIT
mcp-mpv-player
Multimedia Processing Entertainment & Media App Automation
guodaxia9527
A
license
A
quality
D
maintenance
Control mpv media player through AI conversation. Play music and video, manage playlists — all via natural language. Works with opencode and any MCP-compatible AI tool.
Updated 8 months ago (2026-03-22 05:45 UTC)
16
9 npm
MIT
Arr Suite MCP Server
Entertainment & Media Home Automation & IoT
shaktech786
A
license
Not graded
quality
D
maintenance
Enables AI assistants to manage media automation services like Sonarr, Radarr, Prowlarr, Bazarr, Overseerr, and Plex through natural language commands.
Updated a year ago (2025-11-08 22:45 UTC)
19 PyPI
8
MIT

vlc-mcp

Features

Prerequisites

Turn on VLC's HTTP interface

Installation

Configuration

Claude Desktop

Claude Code

Usage

Tools

Development

Security

Project layout

Contributing

Licence

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Spotify MCP Server

Plex Assistant MCP

mcp-mpv-player

Arr Suite MCP Server