mcp梁

mcp-beam app icon

演示

mcp-beam demo

mcp-beam 是MCP服务器(stdio 传输），用于将本地文件和媒体URL投射到局域网上的Chromecast和DLNA/UPnP设备。

它公开了四个工具：

list_local_hardware
beam_media
seek_beaming
stop_beaming

亮点

一台服务器可用于Chromecast和DLNA/UPnP工作流。
稳定的设备ID，用于可靠的后续通话。
协议感知的直接播放和转码决策。
默认情况下，路径、URL和绑定策略是安全的。
带有实用补救提示的结构化错误。

快速开始

几分钟后高兴起来。

1）添加 `mcp-beam` 到您的MCP主机配置

CLI单行程序：

# Claude Code
claude mcp add --scope user mcp-beam -- go run go2tv.app/mcp-beam@latest

# Codex
codex mcp add mcp-beam -- go run go2tv.app/mcp-beam@latest

# Gemini
gemini mcp add mcp-beam go run go2tv.app/mcp-beam@latest

通用JSON配置（适用于使用 mcpServers):

{
  "mcpServers": {
    "mcp-beam": {
      "command": "go",
      "args": [
        "run",
        "go2tv.app/mcp-beam@latest"
      ]
    }
  }
}

笔记：

需要 go 在 PATH （去吧 1.25+).
由于模块下载/构建，第一次运行可能会变慢。

2）验证服务器二进制/模块接线

go run go2tv.app/mcp-beam@latest --version
go run go2tv.app/mcp-beam@latest --self-test

3）运行工具流

呼叫 list_local_hardware 并选择一个设备 id.
呼叫 beam_media 随着 source 和 target_device.
呼叫 seek_beaming 根据需要。
呼叫 stop_beaming 当完成时。

最小示例流：

{
  "name": "list_local_hardware",
  "arguments": {
    "timeout_ms": 3000,
    "include_unreachable": false
  }
}

{
  "name": "beam_media",
  "arguments": {
    "source": "/absolute/path/to/video.mp4",
    "target_device": "dev_1234abcd",
    "transcode": "auto"
  }
}

{
  "name": "seek_beaming",
  "arguments": {
    "session_id": "sess_abcd1234",
    "position_percent": 50
  }
}

{
  "name": "stop_beaming",
  "arguments": {
    "session_id": "sess_abcd1234"
  }
}

安装

已发布模块（推荐）

go run go2tv.app/mcp-beam@latest --version
go run go2tv.app/mcp-beam@latest --self-test

本地结账

从repo根目录：

go run . --version
go run . --self-test

使用此MCP配置直接从源代码运行：

macOS/Linux：

{
  "mcpServers": {
    "mcp-beam": {
      "command": "/bin/bash",
      "args": [
        "-lc",
        "cd /absolute/path/to/mcp-beam && go run ."
      ]
    }
  }
}

Windows PowerShell：

{
  "mcpServers": {
    "mcp-beam": {
      "command": "powershell",
      "args": [
        "-NoProfile",
        "-Command",
        "Set-Location 'C:\\absolute\\path\\to\\mcp-beam'; go run ."
      ]
    }
  }
}

已下载二进制文件

本地构建：

go build -o ./bin/mcp-beam .
./bin/mcp-beam --version
./bin/mcp-beam --self-test

或从以下版本安装：

https://github.com/alex/mcp-beam/releases

Linux/macOS校验和验证：

shasum -a 256 -c SHA256SUMS

Windows校验和验证：

Get-FileHash .\mcp-beam__windows_amd64.zip -Algorithm SHA256

Linux/macOS解包：

tar -xzf mcp-beam___.tar.gz
./mcp-beam___/mcp-beam --version
./mcp-beam___/mcp-beam --self-test

Windows解包：

Expand-Archive .\mcp-beam__windows_amd64.zip -DestinationPath .
.\mcp-beam__windows_amd64\mcp-beam.exe --version
.\mcp-beam__windows_amd64\mcp-beam.exe --self-test

本地二进制文件的MCP配置：

{
  "mcpServers": {
    "mcp-beam": {
      "command": "/absolute/path/to/mcp-beam",
      "args": []
    }
  }
}

运行时依赖关系

go 运行服务器需要（Go 1.25+）。看转到安装在......下面
ffmpeg 和 ffprobe 对于非转码路径是可选的，但建议使用。

- 如果需要转码 ffmpeg 不可用，呼叫返回 FFMPEG_NOT_FOUND.

转到安装

Linux

从下载并安装https://go.dev/dl/或通过包管理器：

Debian/Ubuntu： sudo apt install golang-go
Fedora： sudo dnf install golang
拱门： sudo pacman -S go

macOS

从下载并安装https://go.dev/dl/或使用Homebrew：

brew install go@1.25

视窗

从下载并安装https://go.dev/dl/

验证安装

go version

应输出： go1.25.0 或更高。

安装示例：

Linux:包管理器（例如 sudo apt install ffmpeg)
macOS： brew install ffmpeg
Windows：安装FFmpeg并添加 bin 到 PATH

验证：

Linux/macOS： command -v ffmpeg && command -v ffprobe
窗户： where ffmpeg 和 where ffprobe

工具参考

`list_local_hardware`

在本地网络上发现Chromecast和DLNA/UPnP渲染器。

论据：

timeout_ms （可选整数，最小值 100，默认值 5000)
include_unreachable （可选布尔值，默认值 false)

例子：

{
  "name": "list_local_hardware",
  "arguments": {
    "timeout_ms": 5000,
    "include_unreachable": false
  }
}

关于成功， structuredContent 包括：

count
devices[] 条目：
id
name
type
address
is_audio_only
protocol (chromecast 或 dlna)
capabilities.supports_file_source
capabilities.supports_url_source
capabilities.supports_hls_m3u8_url
capabilities.limitations[]

`beam_media`

在选定的已发现设备上开始播放。

论据：

source （必填字符串）：绝对本地文件路径，或 http/https 统一资源定位符
target_device （必填字符串）：首选稳定的设备ID，精确的名称回退
transcode （可选字符串）： auto （默认）， always, never
subtitles_path （可选字符串）：绝对本地字幕文件路径(.srt 或 .vtt)
start_seconds （可选整数，最小值 0)：从媒体开头开始偏移

例子：

{
  "name": "beam_media",
  "arguments": {
    "source": "/absolute/path/to/media.mp4",
    "target_device": "dev_1234abcd",
    "transcode": "auto",
    "subtitles_path": "/absolute/path/to/subs.srt",
    "start_seconds": 60
  }
}

关于成功， structuredContent 包括：

ok
session_id
device_id
media_url
transcoding
warnings[]

协议说明：

Chromecast支持本地文件和URL源。
Chromecast支持直接 .m3u8 HLS URL转换。
DLNA支持具有直接先代理回退行为的本地文件和URL源。
数字生活网络联盟 .m3u8 URL被拒绝，并带有结构化的限制详细信息。
当 subtitles_path 对于本地文件，mcp-beam会自动检测使用相同基名的sidecar字幕(.srt那么 .vtt).

`stop_beaming`

停止活动光束会话。

论据：

target_device （可选字符串）
session_id （可选字符串）
至少一个 target_device 或 session_id 是必需的。

例子：

{
  "name": "stop_beaming",
  "arguments": {
    "session_id": "sess_abcd1234"
  }
}

关于成功， structuredContent 包括：

ok
stopped_session_id
device_id

`seek_beaming`

根据绝对位置、百分比、端部偏移或相对增量查找活动波束会话。

论据：

target_device （可选字符串）
session_id （可选字符串）
正好是以下之一：
position_seconds （整数，最小值 0)
position_percent （数量、范围 0 到 100)
from_end_seconds （整数，最小值 0)
delta_seconds （整数）：与当前播放位置的相对增量；负值倒带
至少一个 target_device 或 session_id 是必需的。

例子：

{
  "name": "seek_beaming",
  "arguments": {
    "session_id": "sess_abcd1234",
    "from_end_seconds": 10
  }
}

关于成功， structuredContent 包括：

ok
session_id
device_id
position_seconds
requested_mode
resolved_position_seconds
可选的 duration_seconds

示例：

媒体中间： position_percent: 50
距离结束还有10秒： from_end_seconds: 10
精确秒数： position_seconds: 120
向前跳30秒： delta_seconds: 30
倒退10秒： delta_seconds: -10

注：

相对模式(position_percent, from_end_seconds)需要已知的媒体持续时间。

转码行为

beam_media.arguments.transcode 值：

auto （默认）
always
never

行为总结：

never：不要转码。
always：强制对视频源进行转码；对于非视频源忽略。
auto：协议感知默认行为。
Chromecast本地文件：仅在编解码器兼容性需要时进行转码。
Chromecast URL源：默认情况下直接流式传输。
DLNA本地文件：仅使用转码 always 对于视频源。
DLNA URL源：直接优先，然后代理回退；仅使用强制转码 always 视频。

边缘案例：

无效 transcode 值返回JSON-RPC -32602 (invalid params).
transcode=always 使用直接Chromecast HLS(.m3u8)URL被拒绝。
如果需要/请求转码，以及 ffmpeg 不可用，呼叫返回 FFMPEG_NOT_FOUND.
结果包括 structuredContent.transcoding 和 warnings[] 这样呼叫者就可以验证运行了什么。

错误模型

输入验证失败：

JSON-RPC错误 -32602 (invalid params)

工具故障：

isError=true
structuredContent.error 包括：
code
message
可选的 limitations[]
可选的 suggested_fixes[]
可选的 details

常见刀具错误代码：

DEVICE_NOT_FOUND
DEVICE_UNREACHABLE
FILE_NOT_FOUND
FILE_NOT_READABLE
UNSUPPORTED_MEDIA
UNSUPPORTED_SOURCE_FOR_PROTOCOL
UNSUPPORTED_URL_PATTERN
TRANSCODE_REQUIRED
FFMPEG_NOT_FOUND
PROTOCOL_ERROR
INTERNAL_ERROR

环境变量

变量	默认值	效果
`MCP_BEAM_STRICT_PATH_POLICY`	`false`	启用严格的文件/字幕路径允许列表强制。
`MCP_BEAM_ALLOWED_PATH_PREFIXES`	空	严格模式下允许使用逗号分隔的绝对前缀。
`MCP_BEAM_ALLOW_LOOPBACK_URLS`	`false`	允许 `localhost`/环回URL主机 `true`.
`MCP_BEAM_ALLOW_WILDCARD_BIND`	`false`	允许在以下情况下使用通配符绑定地址 `true`.
`MCP_BEAM_LOG_LEVEL`	`info`	服务器日志级别： `debug`, `info`, `warn`, `error`.

安全

安全控制：

本地文件路径必须是绝对路径。
严格路径模式强制使用分配的前缀并拒绝路径转义。
仅 http 和 https URL已被接受。
环回主机(localhost, 127.0.0.0/8, ::1)默认情况下被阻止。
通配符绑定地址(0.0.0.0, ::)默认情况下被阻止。
临时媒体路由使用随机、不可尝试的令牌。
会话所有权是进程本地和内存中的。

推荐生产基准：

保持 MCP_BEAM_ALLOW_LOOPBACK_URLS=false 除非明确需要进行仅限本地的测试。
保持 MCP_BEAM_ALLOW_WILDCARD_BIND=false.
启用 MCP_BEAM_STRICT_PATH_POLICY=true 明确 MCP_BEAM_ALLOWED_PATH_PREFIXES.
跑 mcp-beam 在最低权限OS帐户下。

威胁边界：

MCP客户端输入是不可信的，并且经过严格验证。
源URL主机是外部信任边界。
媒体侦听器在局域网中可见，应仅在受信任的网络上运行。
设备控制端点（Chromecast/DLNA）取决于局域网的完整性。

建筑

MCP Host (MCP client)
        |
        | stdio JSON-RPC (MCP)
        v
  mcp-beam (single process)
  - internal/mcpserver   (initialize, tools/list, tools/call)
  - internal/discovery   (unified DLNA + Chromecast discovery)
  - internal/beam        (session manager + lifecycle + cleanup)
        |
        +--> go2tv castprotocol    (Chromecast control)
        +--> go2tv soapcalls       (DLNA control)
        +--> go2tv httphandlers    (temporary HTTP media serving)
        +--> go2tv utils           (MIME/transcode/url helpers)

运行时模型：

单头二进制。
MCP结束 stdin/stdout 只有。
进程中的会话管理器是真理的来源。
每个目标设备一个活动会话。

核心流量：

list_local_hardware：发现、规范化、稳定的ID，可选的可达性过滤器。
beam_media：验证源、解析目标、选择协议、决定转码、开始播放、持久会话。
seek_beaming：通过以下方式寻求活跃的会议 session_id 或 target_device.
stop_beaming：解析会话/设备，停止协议回放，删除运行时资源。

会话生命周期默认值：

idle_cleanup_after = 10m
paused_cleanup_after = 90m
max_session_age = 24h
扫描间隔 5s

国家来源：

Chromecast通过状态轮询(GetStatus)
DLNA混合监控（回调+轮询回退）

故障排除

快速诊断：

mcp-beam --version
mcp-beam --self-test

详细日志：

MCP_BEAM_LOG_LEVEL=debug mcp-beam

常见问题：

FFMPEG_NOT_FOUND：安装 ffmpeg/ffprobe，然后验证 PATH.
DEVICE_NOT_FOUND：run list_local_hardware 并重新使用 id.
DEVICE_UNREACHABLE：验证目标是否已通电且可访问。
UNSUPPORTED_URL_PATTERN：源必须可路由 http/https；仅用于本地环回测试，请设置 MCP_BEAM_ALLOW_LOOPBACK_URLS=true.
UNSUPPORTED_SOURCE_FOR_PROTOCOL：目标Chromecast .m3u8.
PROTOCOL_ERROR 使用绑定策略：使用具体的LAN绑定地址；集 MCP_BEAM_ALLOW_WILDCARD_BIND=true 仅在受控环境中。
invalid params：删除未知字段并匹配精确的参数名称/类型。

发现问题：

如果没有设备退回，请增加 timeout_ms.
集 include_unreachable=true 用于调试。
验证防火墙/网络发现访问权限。

启动问题：

验证命令路径和可执行权限。
在Windows上，使用完整路径 mcp-beam.exe.
在调试日志中，检查 mcp_server_start, mcp_read_wait, mcp_message_received.

发展

常用命令：

make test
make lint
make release
make clean

MCP Beam

快速接入

详细介绍

mcp梁

演示

亮点

目录

快速开始

1）添加 `mcp-beam` 到您的MCP主机配置

2）验证服务器二进制/模块接线

3）运行工具流

安装

已发布模块（推荐）

本地结账

已下载二进制文件

运行时依赖关系

转到安装

Linux

macOS

视窗

验证安装

工具参考

`list_local_hardware`

`beam_media`

`stop_beaming`

`seek_beaming`

转码行为

错误模型

环境变量

安全

建筑

故障排除

发展

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

MCP Beam

快速接入

详细介绍

mcp梁

演示

亮点

目录

快速开始

1） 添加 mcp-beam 到您的MCP主机配置

2） 验证服务器二进制/模块接线

3） 运行工具流

安装

已发布模块（推荐）

本地结账

已下载二进制文件

运行时依赖关系

转到安装

Linux

macOS

视窗

验证安装

工具参考

list_local_hardware

beam_media

stop_beaming

seek_beaming

转码行为

错误模型

环境变量

安全

建筑

故障排除

发展

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1）添加 `mcp-beam` 到您的MCP主机配置

2）验证服务器二进制/模块接线

3）运行工具流

`list_local_hardware`

`beam_media`

`stop_beaming`

`seek_beaming`