openmedia-mcp

面向 MCP 代理（Agent）的上下文_MCP 服务器套件，用于提取、分析和操作媒体——图像、PDF、视频、音频。

可在任何兼容 MCP 的宿主（harness）中运行（opencode、Claude Code/Desktop、Cursor、Windsurf、Cline、LM Studio 等），传输层支持 stdio、streamable HTTP 或 SSE。

为什么

多模态模型具备视觉能力，但多数 harness 没有提供干净的途径，应用一个视频、一份扫描版 PDF 或一张 20 MB 的照片——要么失败，要么烧掉大量除上下文。openmedia-mcp 通过硬性规定对此作出修复：

• 每个视觉输出都缩小尺寸并按 JPEG 重新压缩后才能到达模型（默认最大边长 / JPEG 质量可配置）。

• 每个文本输出都设置了最大长度，并附上一个显式的截断标记，指引模型如何继续取回更多。

• 每次调用的帧数/页数都有上限（12 帧、8 页），防止意外刷爆上下文。

• URL 被当作一等参与者：视频页面的 URL（YouTube 与 1000+ 站点，经由 yt-dlp）按 ≤720p 载入一次并缓存；直接文件 URL 根据大小上限被缓存。

Related MCP server: Vision MCP Server

系统要求

Python ≥ 3.10 及对应系统结算（全部在调用时刻进行了解析，并带有可操作的错误提示——只有实际调用到的工具才需要自己的二进制）：

可选：pip install "openmedia-mcp[whisper]" 通过 faster-whisper 启用本地语音转文本（audio_transcribe）。

安装与运行

# From a local checkout
uv run --project /path/to/openmedia-mcp openmedia-mcp

# Or install as a tool
uv tool install git+https://github.com/Builderstar/openmedia-mcp.git
openmedia-mcp --tools pdf,image

opencode

{
  "mcp": {
    "openmedia": {
      "type": "local",
      "command": ["uv", "run", "--project", "/home/you/projects/openmedia-mcp", "openmedia-mcp"]
    }
  }
}

Claude Desktop / 通用 MCP 配置

{
  "mcpServers": {
    "openmedia": {
      "command": "uv",
      "args": ["run", "--project", "/home/you/projects/openmedia-mcp", "openmedia-mcp"]
    }
  }
}

HTTP 传输方式

openmedia-mcp --transport streamable-http --host 127.0.0.1 --port 8756

工具集

只用 --tools image,pdf,video,audio 挂载指定 harness 所需的工具集（默认：全部）。media_probe 始终可用。

image

pdf

video

audio

配置（环境）

安全与隐私说明

本服务以启动这些进程的用户权限运行。其工具可以读取本地媒体、查询 URL、运行媒体处理二进制，并向调用方指定的路径写入文件。工具返回值可能包含绝对路径媒体元数据。请只连接可信的 MCP 客户端。

HTTP 传输层并不提供任何身份验证。默认绑定到回环地址，除非已另有专门的认证代理与网络安全策略，否则请勿将它暴露到另一台主机或不可信网络。URL 抓取可能触达本机可见的网络，包括私有网内服务。

可选的 Whisper 工具会在初次使用时下载并缓存 mm 的 base` 版将 faster-whisper 模型。如需离线运行，请提前准备好载入模型缓存。

开发

uv sync                          # install deps
uv run python tests/smoke_test.py [sample-video.mp4]   # exercises every tool

冒烟测试会自己生成测试用图像和 PDF；传入任意本地视频文件即可额外覆盖 video/audio 这两个工具集。

许可证

MIT