英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

让你的会议可被 AI 代理访问 🤖

joinly.ai 是一款连接中间件，旨在使 AI 代理能够加入并积极参与视频通话。通过其 MCP 服务器，joinly.ai 提供了基本的会议工具和资源，可以让任何 AI 代理具备执行任务的技能，并在会议中实时与你互动。

想立即开始？跳转到快速上手！
想了解更多？访问我们的网站 https://joinly.ai/！

[!重要]
不想费心设置一切？先试试我们的云端服务吧！☁️🚀

:sparkles: features

• 实时互动：允许你的 AI 代理在会议中通过语音或聊天实时执行任务和回应
• 对话流程：内置逻辑，可通过处理打断和多说话人互动确保自然对话
• 跨平台：支持加入 Google Meet、Zoom 和 Microsoft Teams（或任何可通过浏览器使用的平台）
• 自带 LLM：兼容所有 LLM 提供商（也可在本地使用 Ollama）
• 选择你喜欢的 TTS/STT：模块化设计支持多项服务——STT 支持 Whisper/Deepgram，TTS 支持 Kokoro/ElevenLabs/Deepgram（未来还会增加更多）
• 100% 开源、自托管且隐私优先 :rocket:

:video_camera: 演示

GitHub

在此演示视频中，joinly 通过访问最新的网络新闻回答了“什么是 Joinly？”这个问题。然后，它在一个 GitHub 演示代码库中创建了一个 issue。

Notion

在此演示视频中，我们通过 MCP 将 joinly 连接到 Notion，并让它在会议中实时编辑页面内容。

对我们下一步应该做什么项目有想法吗？写信告诉我们！ :rocket:

:zap: 快速上手

通过 Docker 与基本会话代理客户端联合运行。

[!重要]
前提条件：Docker 安装

创建一个新文件夹 joinly 或克隆此仓库（对以下步骤不是必需的）。在此目录中，创建一个新的 .env 文件，并填入您要使用的 LLM 提供商的有效 API 密钥，例如 OpenAI：

[!提示]
您可以在 这里 找到 OpenAI API 密钥

# .env
# for OpenAI LLM
# change key and model to your desired one
JOINLY_LLM_MODEL=gpt-4o
JOINLY_LLM_PROVIDER=openai
OPENAI_API_KEY=your-openai-api-key

[!注意]
请参阅 .env.example 以获取完整的配置选项，包括 Anthropic (Claude) 和 Ollama 设置。将占位符值替换为您实际的 API 密钥，并根据需要调整模型名称。删除您不使用的提供商的占位符值。

拉取 Docker 镜像（约 2.3GB，因为它包含了浏览器和模型）：

docker pull ghcr.io/joinly-ai/joinly:latest

在 Zoom、Google Meet 或 Teams 中启动您的会议，并让 joinly 使用会议链接 <MeetingURL> 加入会议。然后，从您创建 .env 文件的文件夹中运行以下命令：

docker run --env-file .env ghcr.io/joinly-ai/joinly:latest --client <MeetingURL>

:red_circle: 有些难以入门吗？让我们在我们的 discord 上一起解决吧！

:technologist: 运行自定义客户端

在快速入门中，我们直接使用 --client 运行 Docker 容器作为客户端。但我们也可以将其作为服务器运行，并从容器外部连接它，这样我们就可以连接其他 MCP 服务器。在这里，我们使用 joinly-client package 运行自定义客户端，并将其连接到 joinly MCP 服务器。

[！重要]
前提条件：完成 快速入门（除了最后一条命令），安装 uv，并打开两个终端

在第一个终端中启动 joinly 服务器（注意，我们这里没有使用 --client，并且仅在 localhost 上发布端口 8000）：

docker run -p 127.0.0.1:8000:8000 ghcr.io/joinly-ai/joinly:latest

[!警告]
联合 MCP 服务器没有身份验证，并接受客户端提供的配置，因此它只能在本地与单个受信任的客户端运行。将其绑定到 localhost（如上所示），不要将端口暴露给网络。

在服务器运行时，在第二个终端窗口启动示例客户端实现以连接到服务器并加入会议：

uvx joinly-client --env-file .env <MeetingUrl>

将 MCP 服务器添加到客户端

通过提供 JSON 配置，将任何 MCP 服务器的工具添加到代理中。配置文件可以在 "mcpServers" 下包含多个条目，这些条目都将在会议中作为工具可用（配置语法请参见 fastmcp 客户端文档）：

{
    "mcpServers": {
        "localServer": {
            "command": "npx",
            "args": ["-y", "package@0.1.0"]
        },
        "remoteServer": {
            "url": "http://mcp.example.com",
            "auth": "oauth"
        }
    }
}

例如，为网络搜索添加一个 Tavily 配置，然后使用名为 config.json 的配置文件运行客户端：

uvx joinly-client --env-file .env --mcp-config config.json <MeetingUrl>

:wrench: 配置

配置可以通过环境变量和/或命令行参数给出。以下是一些常用的配置选项列表，可在启动 Docker 容器时使用：

docker run --env-file .env -p 127.0.0.1:8000:8000 ghcr.io/joinly-ai/joinly:latest <MyOptionArgs>

或者，您可以使用 joinly-client 通过命令行参数传递 --name、--lang 和 提供商设置，这将覆盖服务器的设置：

uvx joinly-client <MyOptionArgs> <MeetingUrl>

基本设置

一般来说，docker 镜像提供了一个默认启动的 MCP 服务器。但为了快速上手，我们还包括了一个可以通过 --client 使用的客户端实现。请注意，在这种情况下不会启动服务器，其他客户端也无法连接到它。

# Start directly as client; default is as server, to which a custom client can connect
--client <MeetingUrl>

# Change participant name (default: joinly)
--name "AI Assistant"

# Change language of TTS/STT (default: en)
# Note, availability depends on the TTS/STT provider
--lang de

# Change host & port of the joinly MCP server
--host 0.0.0.0 --port 8000

提供商

文本转语音

# Kokoro (local) TTS (default)
--tts kokoro
--tts-arg voice=<VoiceName>  # optionally, set different voice

# ElevenLabs TTS, include ELEVENLABS_API_KEY in .env
--tts elevenlabs
--tts-arg voice_id=<VoiceID>  # optionally, set different voice

# Deepgram TTS, include DEEPGRAM_API_KEY in .env
--tts deepgram
--tts-arg model_name=<ModelName>  # optionally, set different model (voice)

转录

# Whisper (local) STT (default)
--stt whisper
--stt-arg model_name=<ModelName>  # optionally, set different model (default: base), for GPU support see below

# Deepgram STT, include DEEPGRAM_API_KEY in .env
--stt deepgram
--stt-arg model_name=<ModelName>  # optionally, set different model

调试

# Start browser with a VNC server for debugging;
# forward the port and connect to it using a VNC client
--vnc-server --vnc-server-port 5900

# Logging
-v  # or -vv, -vvv

# Help
--help

GPU 支持

我们提供一个带有 CUDA GPU 支持的 Docker 镜像，用于在 GPU 上运行转录和 TTS 模型。要使用它，您需要安装 NVIDIA Container Toolkit 并且 CUDA >= 12.6。然后拉取启用 CUDA 的镜像：

docker pull ghcr.io/joinly-ai/joinly:latest-cuda

使用与上面相同的命令以客户端或服务器身份运行，但使用 joinly:{version}-cuda 镜像并设置 --gpus all：

# Run as server
docker run --gpus all --env-file .env -p 8000:8000 ghcr.io/joinly-ai/joinly:latest-cuda -v
# Run as client
docker run --gpus all --env-file .env ghcr.io/joinly-ai/joinly:latest-cuda -v --client <MeetingURL>

默认情况下，joinly 镜像使用 Whisper 模型 base 进行转录，因为它在 CPU 上仍然运行得相当快。对于 cuda，它会自动默认为 distil-large-v3 以显著提高转录质量。您可以通过设置 --stt-arg model_name=<model_name>（例如，--stt-arg model_name=large-v3）来更改模型。但是，docker 镜像中只打包了相应的默认模型，因此在容器启动时它会开始下载模型权重。

:test_tube: 创建您自己的代理

您也可以编写自己的代理并将其连接到我们的 joinly MCP 服务器。请参阅 joinly-client 包的 代码示例 或 client_example.py，如果您希望有一个不依赖我们框架的起点。

joinly MCP 服务器提供以下工具和资源：

工具

• join_meeting - 使用 URL、参与者名称和可选的通行码加入会议
• leave_meeting - 离开当前会议
• speak_text - 使用 TTS 朗读文本（需要 text 参数）
• send_chat_message - 发送聊天消息（需要 message 参数）
• mute_yourself - 静音麦克风
• unmute_yourself - 取消静音麦克风
• get_chat_history - 以 JSON 格式获取当前会议的聊天记录
• get_participants - 以 JSON 格式获取当前会议的参与者
• get_transcript - 以 JSON 格式获取当前会议的转录内容，可选择按分钟过滤
• get_video_snapshot - 获取当前会议的图像，例如查看当前屏幕共享

资源

• transcript://live - 以 JSON 格式的实时会议转录，包括时间戳和发言者信息。可订阅以在添加新的语句时获取实时更新。

:building_construction: 开发 joinly.ai

对于开发，我们建议使用开发容器，它会安装所有必要的依赖项。要开始，请安装 Visual Studio Code 的 DevContainer 扩展，打开仓库并选择 Reopen in Container。

安装可能需要一些时间，因为它会下载所有包以及 Whisper/Kokoro 模型和 Chromium 浏览器。在最后，它会自动调用 download_assets.py 脚本。如果您看到类似 Missing kokoro-v1.0.onnx 的错误，请手动运行此脚本：

uv run scripts/download_assets.py

我们很想看到你在用它做什么或者用它构建了什么。在我们的 discord 展示你的作品。

:pencil2: Roadmap

会议

• 会议聊天访问权限
• 视频通话中的摄像头及状态更新
• 在视频会议中启用屏幕共享
• 参与者元数据及加入/退出
• 改进浏览器代理功能

对话

• 转录的发言者属性
• 改进客户端记忆：减少令牌使用，允许跨会议事件持久化
• 改进语句结束/轮次转换检测
• 会议内部的人类审批机制

集成

• 展示如何使用 A2A 协议添加代理
• 添加更多提供商集成（STT, TTS）
• 集成会议平台 SDK
• 添加替代的开源会议提供商
• 添加对 Speech2Speech 模型的支持

:busts_in_silhouette: 贡献

我们始终欢迎贡献！请随时提交 bug 问题或功能请求。我们会尽力及时审核所有贡献并帮助合并您的更改。

请查看我们的 路线图，有任何问题请随时联系我们！

:memo: 许可证

本项目采用 MIT 许可证 ‒ 详见 LICENSE 文件。

:speech_balloon: 获取帮助

如果您有问题或反馈，或者希望与维护者或其他社区成员交流，请使用以下链接：

• 加入我们的 Discord
• 浏览我们的 GitHub 讨论