# mcp_media_server
## 基本信息
- Slug: `neal3000-mcp_media_server`
- Source: modelscope
- Publisher: @neal3000/mcp_media_server
- Categories: multimedia-processing / entertainment-and-media / app-automation
- Hosted: No
- License: Unknown
- Source URL: https://www.modelscope.cn/mcp/servers/@neal3000/mcp_media_server
## 简介
暂无描述。
## 安装提示

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

## MCP Server 详情

# 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 Licens…