旁白MCP
一个有趣的MCP服务器，可以截图，描述发生了什么变化，生成搞笑的旁白，并将其作为音频播放！
Datathon2025
我们在得克萨斯州农工大学的DATATHON 2025上制作了这个产品，这是一场以人工智能、机器学习、计算机科学、数据科学和统计学为重点的黑客马拉松！
结果：
代理商：第二名🏆
MCP（此仓库）：ElevenLabs的最佳使用🏆
贡献者：
乔纳森·卡尔斯基'29（CS）：
www.linkedin.com/in/jonathan-kalsky
杨'29（CS）：
https://www.linkedin.com/in/nianjin-yang/
伊桑·海因斯'29（CS）：
https://www.linkedin.com/in/ethan-hince-a831a5381/
简短演示：
https://youtu.be/umaCNd4jPfY?si=QRRDb36p3LI-7轮胎
许可证
我们不允许复制、分叉或窃取我们的想法、代码或知识产权。信息电子邮件jonathan.kalsky@gmail.com
特性
连接到我们的 *定制并同时编程* Minecraft Mod，用数据更新HTTP端口
查看：https://github.com/nianjindev/MinecraftMCPSender
有一个UI可以查看端口上的数据。要托管该UI，请运行：
python3 minecraft_reciever.pypython minecraft_reciever.py (windows)否则
- 获取屏幕截图：从目录中检索最后两个屏幕截图
- 描述：使用Gemini分析屏幕截图并描述更改
- 叙述：对你正在做的事情进行有趣、讽刺的叙述
- 音效：自动添加来自MyInstants API的喜剧音效
- 文本转语音：使用ElevenLabs TTS将叙述转换为语音
- 自动清理：仅保留最后5个屏幕截图
设置
- 安装依赖项：
pip install -r requirements.txt- 创建一个
.env使用API密钥文件：
cp .env.example .env
# Edit .env and add your API keys- 获取API密钥：
- Gemini API密钥：https://aistudio.google.com/app/apikey（免费！） - ElevenLabs API密钥：https://elevenlabs.io/app/settings/api-keys（10000字符/月免费）
- 在config/mcp/servers.json中：
- 您可能需要在命令字段中将“Python3”切换为“Python”
用法
运行客户端
Minecraft Mod集成（首选）
要在叙述中包含Minecraft游戏事件：
- 安装Minecraft Fabric mod（请参阅
MinecraftMCP.java) - 运行截图客户端（它会自动启动接收器）：
python mincraft_client_only.py- 启动Minecraft-模组将自动发送事件
叙述者将描述屏幕上发生的事情和游戏中的事件，例如：
- 放置/损坏的块
- 受到的伤害
- 生物特征变化
- 日夜循环
基于上下文的替代屏幕截图客户端
客户端每5秒截取一次屏幕截图，并生成旁白音频：
python screenshot_client.py这将：
- 每5秒截图一次
- 两张截图后，进行比较
- 生成一个有趣的叙述，讲述发生了什么变化
- 转换为语音并自动播放
注： Minecraft接收器在后台自动运行。无需单独启动！
┌─────────────────┐
│ Minecraft Mod│ Java
│ （游戏中）│
└────────┬────────┘
│ HTTP POST
▼
┌─────────────────────┐
│ 地雷接收器│ （Flask HTTP服务器）
│ 端口8080│ 保存到minecraft_data.json
└────────┬────────────┘
│ 文件写入
▼
┌─────────────────────┐
│ minecraft_data.json│ （共享文件）
└────────┬────────────┘
│ 文件的读取
▼
┌─────────────────────┐
│ 屏幕截图_客户端│ 读取文件，调用MCP工具
└────────┬────────────┘
│ MCP呼叫
▼
┌─────────────────────┐
│ mcp_server.py│ 通过get_minecraft_input工具处理数据
└─────────────────────┘
用作MCP服务器
您还可以将其用作Kiro或其他MCP客户端中的MCP服务器：
{
"mcpServers": {
"screenshot-narrator": {
"command": "python",
"args": ["mcp_server.py"],
"env": {
"GEMINI_API_KEY": "your_key",
"ELEVENLABS_API_KEY": "your_key",
"SCREENSHOT_DIR": "./screenshots"
}
}
}
}可用的MCP工具
- get_creenshot：获取最后N个屏幕截图
- get_mincraft_input：接收Minecraft游戏事件
- 描述：分析屏幕截图和/或Minecraft数据
- 叙述：根据描述生成有趣的叙述
- describe_for_narration：组合工具（更快）-一步分析和叙述
- 概括安排：将多个叙述组合成一个句子
- get_sfx：从MyInstants API搜索声音效果
- 文本转语音：使用ElevenLabs将文本转换为语音
运作原理
- 截图：使用macOS
screencapture抓取屏幕截图 - 分析：Gemini 2.5 Flash分析图像并描述更改（快速免费！）
- 叙述+SFX关键字：Gemini在一个API调用中生成讽刺评论并提取最佳音效关键字（超快！）
- 音效搜索：使用AI选择的关键字搜索MyInstants API，并从顶部结果中随机选择
- 言语：ElevenLabs TTS将文本转换为具有高质量语音的音频
- 回放：同时播放音效和旁白音频，以获得完美的时机
输出示例
📸 Screenshot saved: screenshots/screenshot_20251108_143022.png
📸 Screenshot saved: screenshots/screenshot_20251108_143027.png
==================================================
🎬 Processing screenshots...
==================================================
📋 Getting screenshots...
🔍 Describing changes...
Description: The user has switched from their code editor to a web browser,
apparently giving up on debugging to search Stack Overflow instead.
🎭 Generating funny narration...
Narration: And here we observe the developer in their natural habitat,
abandoning all hope of solving the problem themselves and turning to the
ancient wisdom of strangers on the internet. Truly magnificent.
🎤 Converting to speech...
🔊 Playing audio: screenshots/narration_20251108_143030.mp3文档
- QUICKSTART_SFX.md：音效快速入门指南（3分钟！）
- SFX_集成.md：完整的音效系统指南
- 实施\_ SUMMARY.md：技术实施细节
- myinstants api/README.md：MyInstants API文档
备注
- 跨平台：适用于macOS、Windows和Linux
- 费用：Gemini免费+ElevenLabs每月有10000个字符的免费等级
- Gemini 2.5 Flash在视觉任务中速度极快
- ElevenLabs的声音非常逼真和富有表现力
- MyInstants API提供免费音效
- 按Ctrl+C停止客户端
平台特定详细信息：
- macOS：使用本地
screencapture和afplay命令 - 视窗：使用PIL进行截图，使用pygame进行音频
- Linux：用途
scrot/gnome-screenshot用于截图、各种音频播放器
许可和归属
本项目使用以下声音效果：
- MyInstants API 作者：abdiputranar：https://github.com/abdipr/myinstants-api
- MyInstants.com: https://www.myinstants.com
声音效果是通过MyInstants.com的网页抓取获得的。这个项目：
- 提供对MyInstants API和MyInstants.com的正确归因
- 仅用于非商业、教育和娱乐目的
- 符合MyInstants API使用要求
- 不滥用API获取个人商业利益
如果您使用此项目，请保持此归因并遵循相同的指导方针。
定制
- 改变
INTERVAL在screenshot_client.py调整截图频率 - 修改中的叙述提示
mcp_server.py不同喜剧风格 - 更改TTS语音
mcp_server.py（ElevenLabs配音：Adam、Antoni、Arnold、Bella、Domi、Elli、Josh、Rachel、Sam等） - 在中自定义SFX选择逻辑
get_sfx_for_narration()匹配不同关键字的函数
音效
系统使用AI为每个旁白自动选择完美的音效：
- AI关键词提取：Gemini分析叙述并提取声音效果的最佳关键字（例如，“crash”、“laugh”、“explosion”、“oof”、“bruh”、“screar”等）
- MyInstants搜索：使用该关键字搜索MyInstants API
- 随机选择：从前10个结果中随机选择一个声音，以获得多样性
- 并行播放：同时播放音效和旁白，以获得完美的喜剧时机
这提供了无限的多样性——每个叙述都有一个独特的、与语境相适应的声音效果！
AI提取的关键字示例：碰撞、大笑、爆炸、尖叫、铃声、鼓声、呜呜声、哎哟声、喘息声、掌声、号角声、拳击声、摔倒声等等！
鸣谢
音效由以下设备提供：
- MyInstants API: https://github.com/abdipr/myinstants-api（通过abdiputranar）
- MyInstants.com: https://www.myinstants.com（原始声音库）
声音是从MyInstants.com通过网络抓取获得的。该项目通过提供正确的归属符合API的使用要求，仅用于非商业和教育目的。