AI导哈

媒体服务器

MCP媒体服务器是一个用于列出和播放媒体文件的服务器和客户端，支持stdio、HTTP和HTTPS传输协议，兼容Claude Desktop。

  • by neal3000
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 neal3000/mcp_media_server

使用说明

MCP媒体服务器

一个用于列出和播放媒体文件的模型上下文协议（MCP）服务器和客户端 ~/Media/MOVIES支持stdio、HTTP和HTTPS传输协议，与Claude Desktop兼容。

特点

  • 列出电影浏览您“电影”目录中的所有媒体文件
  • 播放电影使用系统默认媒体播放器开始播放
  • 多种运输方式stdio（用于Claude桌面版）、HTTP和HTTPS
  • 跨平台在Linux上运行（之后也支持macOS和Windows）

安装

# Install dependencies
pip install -r requirements.txt

# Or install individually
pip install mcp starlette uvicorn sse-starlette

快速入门

服务器

stdio（针对Claude桌面版）：

python media_server.py --transport stdio

HTTP:（超文本传输协议）

python media_server.py --transport http --host 0.0.0.0 --port 3000

HTTPS： 没有内置的HTTPS（无论怎么说）使用Caddy作为反向代理来处理HTTPS，并将HTTP请求转发到media_server


### Client

**List movies via stdio:**
```bash
python media_client.py --protocol stdio --command list

通过标准输入输出流播放电影：

python media_client.py --protocol stdio --command play --movie "example.mp4"

通过HTTP列出电影：

python media_client.py --protocol http --url http://localhost:3000/sse --command list

通过HTTPS播放电影：

python media_client.py --protocol https --url https://localhost:3001/sse \
    --command play --movie "example.mp4"

用于https的代理服务器（或：https的代理）

pi5c.example.com:3001 {
	tls /etc/caddy/certs/fullchain.pem /etc/caddy/certs/privkey.pem
	reverse_proxy localhost:3000
}

在我的情况下，“pi5c.example.com”是一个具有本地IP的公共DNS条目。肯定有更好的方法， 但目前它还能用。

我有一个针对 *.example.com 的通配符证书，我已经将其复制到本地 将证书复制到 /etc/caddy/certs/ 目录（如果该目录不存在，请先创建），并将所有者更改为 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

配置

媒体目录

默认情况下，服务器会在 ~/Media/MOVIES要更改这一点，请编辑 MEDIA_DIR 变量在 media_server.py：

MEDIA_DIR = Path.home() / "Media" / "MOVIES"

支持的文件类型

支持以下视频格式：

  • .mp4, .mkv, .avi, .mov, .wmv, .flv, .webm, .m4v, .mpg, .mpeg（这些是视频文件的常见扩展名，翻译为中文即：.mp4、.mkv、.avi、.mov、.wmv、.flv、.webm、.m4v、.mpg、.mpeg）

要添加更多格式，请编辑 MEDIA_EXTENSIONS 设定为 media_server.py。

Claude桌面集成

添加到您的Claude桌面配置中（claude_desktop_config.json):

{
  "mcpServers": {
    "media-server": {
      "command": "python",
      "args": ["/path/to/media_server.py", "--transport", "stdio"]
    }
  }
}

n8n 集成

未经测试 对于 n8n，请使用 HTTP 或 HTTPS 传输方式：

  1. 使用HTTP/HTTPS传输启动服务器
  2. 在 n8n 中，使用 HTTP 请求节点来连接到 http://your-server:8000/sse
  3. 使用POST请求来 /messages MCP通信的端点

媒体播放器要求

服务器将自动检测并使用可用的媒体播放器：

Linux：

  • MPV（多用途汽车）mpv这是唯一一个能可靠运行的播放器
  • VLC（vlc）
  • MPlayer（mplayer）
  • 或系统默认（xdg-open)

macOS：

  • 用途 open 命令（系统默认播放器）

Windows：

  • 用途 os.startfile() （系统默认播放器）

安装播放器（Linux）

# Ubuntu/Debian
sudo apt install vlc

# Fedora
sudo dnf install vlc

# Arch
sudo pacman -S vlc

API 参考文档

工具

列出电影

列出Movies目录中的所有媒体文件。

参数： 无

返回值： 包含电影名称、路径、大小和文件类型的列表

示例：

{
  "name": "list_movies",
  "arguments": {}
}

播放电影

使用系统默认的媒体播放器播放特定的电影。

参数：

  • filename （字符串，必填）：电影文件的名称

返回值： 状态消息，指示成功或错误

示例：

{
  "name": "play_movie",
  "arguments": {
    "filename": "example.mp4"
  }
}

服务器命令行选项

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)

客户端命令行选项

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)

故障排除

未找到媒体播放器

安装MPV或其他支持的媒体播放器：

sudo apt install mpv  # Linux

HTTP/HTTPS 连接错误

  • 检查服务器是否正在运行
  • 验证URL中是否包含 /sse 终端节点
  • 对于HTTPS，请确保证书文件有效

权限错误

确保 ~/Media/MOVIES 目录存在且可读：

mkdir -p ~/Media/MOVIES
chmod 755 ~/Media/MOVIES

安全注意事项

  • 服务器仅访问配置的媒体目录中的文件
  • 服务器不会修改或删除任何文件

许可证

MIT 许可证 - 欢迎根据需要自由使用和修改。

相关 MCP