README.md•6.04 kB
# 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
```bash
# Install dependencies
pip install -r requirements.txt
# Or install individually
pip install mcp starlette uvicorn sse-starlette
```
## Quick Start
### Server
**stdio (for Claude Desktop):**
```bash
python media_server.py --transport stdio
```
**HTTP:**
```bash
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
```bash
### Client
**List movies via stdio:**
```bash
python media_client.py --protocol stdio --command list
```
**Play movie via stdio:**
```bash
python media_client.py --protocol stdio --command play --movie "example.mp4"
```
**List movies via HTTP:**
```bash
python media_client.py --protocol http --url http://localhost:3000/sse --command list
```
**Play movie via HTTPS:**
```bash
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`:
```python
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`):
```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)
```bash
# 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:**
```json
{
"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:**
```json
{
"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:
```bash
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:
```bash
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.