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:**

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 License - Feel free to use and modify as needed.