MCP Media Server

A Model Context Protocol (MCP) server and client for listing and playing media files from ~/Media/MOVIES. Supports stdio, HTTP, and HTTPS transports, compatible with Claude Desktop.

Features

List Movies: Browse all media files in your Movies directory
Play Movies: Start playback using system default media player
Multiple Transports: stdio (for Claude Desktop), HTTP, and HTTPS
Cross-Platform: Works on Linux, ( later macOS, and Windows )

Installation

# Install dependencies pip install -r requirements.txt # Or install individually pip install mcp starlette uvicorn sse-starlette

Quick Start

Server

stdio (for Claude Desktop):

python media_server.py --transport stdio

HTTP:

python media_server.py --transport http --host 0.0.0.0 --port 3000

HTTPS: there is no built in https (regardless of what said) use Caddy as reverse proxy to handle https and forwad http to media_server

### Client **List movies via stdio:** ```bash python media_client.py --protocol stdio --command list

Play movie via stdio:

python media_client.py --protocol stdio --command play --movie "example.mp4"

List movies via HTTP:

python media_client.py --protocol http --url http://localhost:3000/sse --command list

Play movie via HTTPS:

python media_client.py --protocol https --url https://localhost:3001/sse \ --command play --movie "example.mp4"

Caddy for https

pi5c.example.com:3001 { tls /etc/caddy/certs/fullchain.pem /etc/caddy/certs/privkey.pem reverse_proxy localhost:3000 }

In my case "pi5c.example.com" is public DNS entry with a local IP. There has got to be a better way, but it works for now.

I have a wildcard cert for *.example.com which I copied locally Copy the certs to /etc/caddy/certs/ (create if missing) and change owner to caddy

mkdir -p /etc/caddy/certs cp /etc/letsencrypt/live/example.com/fullchain.pem /etc/caddy/certs/ cp /etc/letsencrypt/live/example.com/privkey.pem /etc/caddy/certs/ chown caddy:caddy /etc/caddy/certs/* chmod 644 /etc/caddy/certs/fullchain.pem chmod 600 /etc/caddy/certs/privkey.pem

Configuration

Media Directory

By default, the server looks for media files in ~/Media/MOVIES. To change this, edit the MEDIA_DIR variable in media_server.py:

MEDIA_DIR = Path.home() / "Media" / "MOVIES"

Supported File Types

The following video formats are supported:

.mp4, .mkv, .avi, .mov, .wmv, .flv, .webm, .m4v, .mpg, .mpeg

To add more formats, edit the MEDIA_EXTENSIONS set in media_server.py.

Claude Desktop Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{ "mcpServers": { "media-server": { "command": "python", "args": ["/path/to/media_server.py", "--transport", "stdio"] } } }

n8n Integration

UNTESTED For n8n, use the HTTP or HTTPS transport:

Start the server with HTTP/HTTPS transport
In n8n, use the HTTP Request node to connect to http://your-server:8000/sse
Use POST requests to /messages endpoint for MCP communication

Media Player Requirements

The server will automatically detect and use available media players:

Linux:

MPV (mpv) this is the only player that works reliably
VLC (vlc)
MPlayer (mplayer)
Or system default (xdg-open)

macOS:

Uses open command (system default player)

Windows:

Uses os.startfile() (system default player)

Install a Player (Linux)

# Ubuntu/Debian sudo apt install vlc # Fedora sudo dnf install vlc # Arch sudo pacman -S vlc

API Reference

Tools

list_movies

Lists all media files in the Movies directory.

Arguments: None

Returns: List of movies with name, path, size, and file type

Example:

{ "name": "list_movies", "arguments": {} }

play_movie

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

Arguments:

filename (string, required): Name of the movie file

Returns: Status message indicating success or error

Example:

{ "name": "play_movie", "arguments": { "filename": "example.mp4" } }

Server Command-Line Options

usage: media_server.py [-h] [--transport {stdio,http,https}] [--host HOST] [--port PORT] [--certfile CERTFILE] [--keyfile KEYFILE] optional arguments: --transport {stdio,http} Transport protocol to use (default: stdio) --host HOST Host to bind to for HTTP/HTTPS (default: 127.0.0.1) --port PORT Port to bind to for HTTP/HTTPS (default: 8000)

Client Command-Line Options

usage: media_client.py [-h] --protocol {stdio,http,https} --command {list,play} [--movie MOVIE] [--url URL] [--server-script SERVER_SCRIPT] optional arguments: --protocol {stdio,http,https} Protocol to use for connecting to server --command {list,play} Command to execute (list or play) --movie MOVIE Movie filename to play (required for 'play' command) --url URL Server URL for HTTP/HTTPS (e.g., http://localhost:8000/sse) --server-script SERVER_SCRIPT Path to server script for stdio (default: media_server.py)

Troubleshooting

No media player found

Install MPV or another supported media player:

sudo apt install mpv # Linux

Connection errors with HTTP/HTTPS

Check that the server is running
Verify the URL includes /sse endpoint
For HTTPS, ensure certificate files are valid

Permission errors

Ensure the ~/Media/MOVIES directory exists and is readable:

mkdir -p ~/Media/MOVIES chmod 755 ~/Media/MOVIES

Security Notes

The server only accesses files in the configured media directory
The server does not modify or delete any files

License

MIT License - Feel free to use and modify as needed.

MCP Media Server

MCP Media Server

Features

Installation

Quick Start

Server

Caddy for https

Configuration

Media Directory

Supported File Types

Claude Desktop Integration

n8n Integration

Media Player Requirements

Install a Player (Linux)

API Reference

Tools

list_movies

play_movie

Server Command-Line Options

Client Command-Line Options

Troubleshooting

No media player found

Connection errors with HTTP/HTTPS

Permission errors

Security Notes

License

Related Resources

New MCP Servers

MCP directory API