Skip to main content
Glama

MCP Media Server

by neal3000
GitHub
Python
  • Linux
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables browsing and playing media files from a local Movies directory through natural language commands. Supports listing all movies and launching playback using the system's default media player.

  1. Features
    1. Installation
      1. Quick Start
        1. Server
      2. Caddy for https
        1. Configuration
          1. Media Directory
          2. Supported File Types
        2. Claude Desktop Integration
          1. n8n Integration
            1. Media Player Requirements
              1. Install a Player (Linux)
            2. API Reference
              1. Tools
            3. Server Command-Line Options
              1. Client Command-Line Options
                1. Troubleshooting
                  1. No media player found
                  2. Connection errors with HTTP/HTTPS
                  3. Permission errors
                2. Security Notes
                  1. License

                    New MCP Servers

                    MCP directory API

                    We provide all the information about MCP servers via our MCP API.

                    curl -X GET 'https://glama.ai/api/mcp/v1/servers/neal3000/mcp_media_server'

                    If you have feedback or need assistance with the MCP directory API, please join our Discord server