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:

1. Start the server with HTTP/HTTPS transport
2. In n8n, use the HTTP Request node to connect to http://your-server:8000/sse
3. 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 Licens…