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 stdioHTTP:（超文本传输协议）
python media_server.py --transport http --host 0.0.0.0 --port 3000HTTPS： 没有内置的HTTPS（无论怎么说）使用Caddy作为反向代理来处理HTTPS，并将HTTP请求转发到media_server
### Client
**List movies via stdio:**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传输启动服务器
1. 在 n8n 中，使用 HTTP 请求节点来连接到 `http://your-server:8000/sse`
1. 使用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 许可证 - 欢迎根据需要自由使用和修改。