MCP Media Server

You run a lightweight MCP server that lists and plays media files from your MOVIES directory. It supports multiple transports (stdio for Claude Desktop, HTTP, and HTTPS via a reverse proxy) and automatically uses an available media player on your system to start playback.

How to use

To list movies or play a movie, you connect a client to the MCP server using one of the supported transports. You can use the stdio transport for local desktop workflows or HTTP transport to reach the server over a network. Playback uses your system’s default media player or a specifically installed player if available.

How to install

Prerequisites you need before installation are Python and pip, since the server is Python-based.

Install dependencies using either the full requirements file or individual packages.

pip install -r requirements.txt

# Or install individually
pip install mcp starlette uvicorn sse-starlette

Additional setup and usage notes

Configure the media directory and supported file types in the server source if you customize beyond the defaults.

There is no built-in HTTPS handling in the server; use a reverse proxy like Caddy to terminate TLS and forward requests to the server.

Supported media directory and file types include common video formats such as MP4, MKV, AVI, and more. The server will automatically detect available media players on your system for playback.

Claude Desktop integration

Add an MCP server entry so Claude Desktop can start the local stdio server from your environment.

Troubleshooting

No media player found: install a compatible player (for Linux, MPV is commonly reliable). Ensure the Movies directory exists and is readable.

HTTP/HTTPS connection issues: verify the server is running and that you are using the correct /sse endpoint in the URL. For HTTPS, ensure TLS termination is correctly configured on the reverse proxy.

Notes and security

The server only accesses files within the configured media directory and does not modify or delete any files.

Available tools

list_movies

Lists all media files in the Movies directory with name, path, size, and file type.

play_movie

Plays a specific movie using the system's default media player.