Teamspeak Mcp

Teamspeak Mcp

翻译 Python

🚀 TeamSpeak MCP

TeamSpeak MCP 是一个基于模型上下文协议（MCP）的服务器，可让 Claude 等 AI 模型对 TeamSpeak 进行控制。借助它，能够实现从 AI 端对 TeamSpeak 服务器的各类操作，提升管理效率与自动化程度。

🚀 快速开始

自动安装脚本

python install.py

连接测试

python test_mcp.py

使用 Docker

# 构建镜像
docker build -t teamspeak-mcp .

# 使用 Docker 进行测试
docker run --rm -it \
-e TEAMSPEAK_HOST=your-server.com \
-e TEAMSPEAK_USER=your-user \
-e TEAMSPEAK_PASSWORD=your-password \
teamspeak-mcp test

✨ 主要特性

  • 🎯 连接到 TeamSpeak 服务器
  • 💬 向频道发送消息、发送私聊消息和戳人提醒（警报通知）
  • 📋 列出已连接的用户和详细的客户端信息
  • 🔧 高级频道管理（创建、删除、更新属性和权限）
  • 🔇 AFK/静音频道设置，支持预设通话权限
  • 🎵 语音控制（静音、取消静音、踢出、封禁）
  • 🛡️ 针对每个频道的细粒度权限管理
  • 🖥️ 虚拟服务器配置（名称、描述、限制、欢迎消息）
  • 👥 用户权限管理（服务器组、个人权限）
  • 📊 全面的服务器和频道诊断
  • 📝 增强的日志系统，具备以下功能：
    • 自动日志配置
    • 日志诊断
    • 实例级日志
    • 高级过滤
    • 实时通知
  • ⚙️ 39 个强大的工具，可实现完整的 TeamSpeak 自动化

📦 安装指南

要求

  • Python 3.10 - 3.12
  • Docker（可选，用于容器化部署）
  • 启用 ServerQuery 的 TeamSpeak 3 服务器

🎯 集成方法概述

TeamSpeak MCP 提供多种集成方法，以适应不同的设置和偏好：

📦 方法 1：PyPI 包（推荐给大多数用户）

  • ✅ 最简便的设置 - 一键安装
  • ✅ 通过标准包管理器实现自动更新
  • ✅ 标准 MCP 模式 - 与 Claude Desktop 示例兼容
  • ✅ 无需 Docker - 纯 Python 实现
# 安装
uvx install teamspeak-mcp

# 使用
uvx teamspeak-mcp --host your-server.com --user your-user --password your-password

# Claude Desktop 配置（CLI 参数）
{
"mcpServers": {
"teamspeak": {
"command": "uvx",
"args": ["teamspeak-mcp", "--host", "your-server.com", "--user", "your-user", "--password", "your-password"]
}
}
}

🐳 方法 2：预构建的 Docker 镜像（推荐用于容器化部署）

  • ✅ 无依赖项 - 所有内容都包含在内
  • ✅ 版本一致性 - 不可变部署
  • ✅ 易于扩展 - 可与编排工具配合使用
  • ✅ 跨平台 - 可在任何运行 Docker 的地方使用

💡 注意：我们在参数中使用 -e 标志，而不是 "env": {} 字段，因为 Claude Desktop 的环境变量处理可能不可靠。使用参数方法可确保变量传递一致。

# 安装
docker pull ghcr.io/marlburrow/teamspeak-mcp:latest

# Claude Desktop 配置（参数中的环境变量）
{
"mcpServers": {
"teamspeak": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "TEAMSPEAK_HOST=your-server.com",
"-e", "TEAMSPEAK_USER=your-user",
"-e", "TEAMSPEAK_PASSWORD=your-password",
"ghcr.io/marlburrow/teamspeak-mcp:latest"
]
}
}
}

🐍 方法 3：本地 Python 安装（适用于开发者）

  • ✅ 完全控制 - 可访问源代码
  • ✅ 可定制 - 可根据特定需求进行修改
  • ✅ 便于开发 - 可对项目做出贡献
  • ⚠️ 设置步骤较多 - 需要管理 Python 环境
# 安装
git clone https://github.com/MarlBurroW/teamspeak-mcp.git
cd teamspeak-mcp && pip install -r requirements.txt

# Claude Desktop 配置（Python 模块）
{
"mcpServers": {
"teamspeak": {
"command": "python",
"args": ["-m", "teamspeak_mcp.server", "--host", "your-server.com", "--user", "your-user", "--password", "your-password"]
}
}
}

🏗️ 方法 4：本地 Docker 构建（适用于自定义需求）

  • ✅ 自定义构建 - 可根据需要修改 Dockerfile
  • ✅ 离线使用 - 无需外部依赖
  • ✅ 版本控制 - 可固定到特定提交
  • ⚠️ 构建时间长 - 需要本地进行 Docker 构建
# 安装
git clone https://github.com/MarlBurroW/teamspeak-mcp.git
cd teamspeak-mcp && docker build -t teamspeak-mcp .

# Claude Desktop 配置（本地镜像）
{
"mcpServers": {
"teamspeak": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "TEAMSPEAK_HOST=your-server.com",
"-e", "TEAMSPEAK_USER=your-user",
"-e", "TEAMSPEAK_PASSWORD=your-password",
"teamspeak-mcp"
]
}
}
}

🎯 应该选择哪种方法？

使用场景 推荐方法 原因
首次使用的用户 PyPI 包 (uvx) 设置最简单，采用标准 MCP 模式
生产环境部署 预构建的 Docker 镜像 可靠、有版本控制、无依赖项
CI/CD 环境 预构建的 Docker 镜像 部署一致、快速
开发/贡献代码 本地 Python 安装 可完全访问源代码
自定义修改 本地 Docker 构建 构建过程可控
企业环境 本地 Docker 构建 无需外部依赖

💡 快速开始示例

最快的方式（PyPI）：

uvx install teamspeak-mcp
# 使用 CLI 参数添加到 Claude Desktop 配置中

最可靠的方式（Docker）：

docker pull ghcr.io/marlburrow/teamspeak-mcp:latest
# 使用参数中的环境变量添加到 Claude Desktop 配置中

最灵活的方式（本地）：

git clone https://github.com/MarlBurroW/teamspeak-mcp.git
cd teamspeak-mcp && pip install -r requirements.txt
# 使用 Python 模块添加到 Claude Desktop 配置中

🔑 TeamSpeak 服务器设置

在使用 TeamSpeak MCP 之前，需要配置 TeamSpeak 服务器的凭据：

📋 所需信息

参数 描述 示例
TEAMSPEAK_HOST 服务器 IP 或域名 ts.example.com 或 192.168.1.100
TEAMSPEAK_PORT ServerQuery 端口（默认：10011） 10011
TEAMSPEAK_USER ServerQuery 用户名 mcp_user
TEAMSPEAK_PASSWORD ServerQuery 密码 secure_password123
TEAMSPEAK_SERVER_ID 虚拟服务器 ID（通常为 1） 1

🔧 如何获取凭据

步骤 1：启用 ServerQuery

在 TeamSpeak 服务器上，确保 ServerQuery 已启用：

  • 检查 ts3server.ini：query_port=10011
  • 大多数安装默认已启用

步骤 2：获取管理员权限

  • 首次安装：检查服务器日志中的管理员令牌：token=AAAA...
  • 现有服务器：使用管理员凭据

步骤 3：创建 MCP 用户

连接到 ServerQuery 并创建一个专用用户：

# 通过 telnet 或 putty 连接到 your-server:10011
telnet your-server.example.com 10011

# 使用管理员登录
login serveradmin YOUR_ADMIN_PASSWORD

# 为 MCP 创建专用用户
serverqueryadd client_login_name=mcp_user client_login_password=secure_password123

# 授予必要的权限（可选 - 根据需要调整）
servergroupaddclient sgid=6 cldbid=USER_DB_ID

步骤 4：测试连接

# 使用我们的连接脚本进行测试
python test_mcp.py

# 或者使用 Docker 进行测试
docker run --rm -it \
-e TEAMSPEAK_HOST=your-server.example.com \
-e TEAMSPEAK_USER=mcp_user \
-e TEAMSPEAK_PASSWORD=secure_password123 \
ghcr.io/marlburrow/teamspeak-mcp:latest test

💡 快速配置示例

对于 PyPI 安装：

{
"mcpServers": {
"teamspeak": {
"command": "uvx",
"args": ["teamspeak-mcp", "--host", "your-server.example.com", "--user", "mcp_user", "--password", "secure_password123"]
}
}
}

对于 Docker 安装：

{
"mcpServers": {
"teamspeak": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "TEAMSPEAK_HOST=your-server.example.com",
"-e", "TEAMSPEAK_USER=mcp_user",
"-e", "TEAMSPEAK_PASSWORD=secure_password123",
"ghcr.io/marlburrow/teamspeak-mcp:latest"
]
}
}
}

⚠️ 重要提示

创建一个具有最小权限的专用 ServerQuery 用户。切勿将管理员账户用于自动化工具。

💻 使用示例

基本命令

  • "连接到 TeamSpeak 服务器"
  • "向通用频道发送消息 '大家好！'"
  • "向用户 5 发送私聊消息 '你能加入我吗？'"
  • "用消息 '紧急：请查看公告！' 戳用户 12"
  • "列出已连接的用户"
  • "创建一个名为 '会议' 的临时频道"
  • "将用户 John 移动到私聊频道"
  • "显示服务器信息"

高级命令

  • "将频道 5 设置为静音，使任何人都无法发言" → 使用 set_channel_talk_power 并预设为 "静音"
  • "设置一个有主持人的欢迎频道" → 使用 set_channel_talk_power 并预设为 "有主持人"
  • "更新频道 3，将最大客户端数设置为 10 并添加密码 'secret'" → 使用 update_channel
  • "显示频道 7 的详细信息" → 使用 channel_info
  • "获取客户端 12 的全面详细信息" → 使用 client_info_detailed
  • "列出频道 4 的所有权限" → 使用 manage_channel_permissions 并执行 "列出" 操作
  • "向频道 6 添加通话权限" → 使用 manage_channel_permissions 并执行 "添加" 操作
  • "将服务器名称更改为 '我的游戏服务器' 并将最大客户端数设置为 100" → 使用 update_server_settings
  • "将欢迎消息设置为 '欢迎来到我们的服务器！'" → 使用 update_server_settings
  • "将用户 15 添加到管理员组 6" → 使用 manage_user_permissions 并执行 "添加组" 操作
  • "将用户 8 从主持人组中移除" → 使用 manage_user_permissions 并执行 "移除组" 操作
  • "显示用户 12 的所有服务器组" → 使用 manage_user_permissions 并执行 "列出组" 操作
  • "给予用户 20 'b_client_kick' 权限，值为 75" → 使用 manage_user_permissions 并执行 "添加权限" 操作
  • "诊断我当前的权限和连接情况" → 使用 diagnose_permissions
  • "检查我无法列出客户端的原因" → 使用 diagnose_permissions

🎯 可用工具（共 39 个）

核心工具（共 12 个）

  • connect_to_server : 连接到 TeamSpeak 服务器
  • send_channel_message : 向频道发送消息
  • send_private_message : 发送私聊消息
  • poke_client : 向用户发送戳人提醒（警报通知） - 比私聊消息更引人注意
  • list_clients : 列出已连接的客户端
  • list_channels : 列出频道
  • create_channel : 创建新频道
  • delete_channel : 删除频道
  • move_client : 将客户端移动到另一个频道
  • kick_client : 踢出客户端
  • ban_client : 封禁客户端
  • server_info : 获取服务器信息

🆕 高级管理工具（共 8 个）

  • update_channel : 更新频道属性（名称、描述、密码、通话权限、限制等）
  • set_channel_talk_power : 使用预设快速设置 AFK/静音/有主持人的频道
  • channel_info : 获取详细的频道信息（权限、编解码器、类型等）
  • manage_channel_permissions : 细粒度的权限控制（添加/移除/列出）
  • client_info_detailed : 全面的客户端详细信息（平台、版本、状态等）
  • update_server_settings : 更新虚拟服务器设置（名称、欢迎消息、最大客户端数、密码、主机消息、默认组）
  • manage_user_permissions : 完整的用户权限管理（添加/移除服务器组、设置个人权限、列出分配情况）
  • diagnose_permissions : 诊断当前连接权限并排查问题

🆕 服务器组管理（共 4 个）

  • list_server_groups : 列出所有可用的服务器组
  • assign_client_to_group : 将客户端添加或移除服务器组
  • create_server_group : 创建具有自定义设置的新服务器组
  • manage_server_group_permissions : 管理服务器组的权限

🆕 审核与封禁（共 3 个）

  • list_bans : 列出服务器上所有活动的封禁规则
  • manage_ban_rules : 创建、删除或管理封禁规则（基于 IP、名称、UID）
  • list_complaints : 列出对用户的投诉

🆕 搜索与发现（共 2 个）

  • search_clients : 按名称模式或唯一标识符搜索客户端
  • find_channels : 按名称模式搜索频道

🆕 特权令牌（共 2 个）

  • list_privilege_tokens : 列出所有可用的特权密钥/令牌
  • create_privilege_token : 创建用于服务器/频道访问的新特权令牌

🆕 文件管理（共 3 个）

  • list_files : 列出频道文件存储库中的文件
  • get_file_info : 获取特定文件的详细信息
  • manage_file_permissions : 列出和管理活动的文件传输

🆕 日志与监控（共 3 个）

  • view_server_logs : 查看服务器日志的最近条目
  • add_log_entry : 向服务器日志添加自定义条目
  • get_connection_info : 获取详细的连接信息

🆕 快照与备份（共 2 个）

  • create_server_snapshot : 创建服务器配置的快照
  • deploy_server_snapshot : 从快照部署/恢复服务器配置

🔧 技术细节

本地测试

# 安装开发依赖项
pip install -r requirements.txt

# 运行测试
python test_mcp.py

# 启动 MCP 服务器
python -m teamspeak_mcp.server

Docker 构建

# 构建
docker build -t teamspeak-mcp .

# 测试
docker run --rm -it teamspeak-mcp

安全措施

  • 🔑 切勿在代码中提交凭据
  • 🛡️ 使用具有有限权限的 ServerQuery 账户
  • 🌐 配置防火墙以限制对 ServerQuery 端口的访问
  • 🔄 定期更改 ServerQuery 密码

自动化发布工作流（适用于维护者）

本项目通过 GitHub Actions 实现了完全自动化的发布，无需手动上传到 PyPI！

工作原理：

  1. 一键发布：

    # 补丁版本发布（1.0.3 -> 1.0.4）
make release-patch

# 小版本发布（1.0.3 -> 1.1.0） 
make release-minor

# 大版本发布（1.0.3 -> 2.0.0）
make release-major

  2. 自动化流程：

    • ✅ 自动更新 pyproject.toml 中的版本号
    • ✅ 创建 git 提交和标签
    • ✅ 推送到 GitHub
    • ✅ 自动触发 GitHub Actions：
      • 🔨 构建 Python 包
      • 🧪 首先在 TestPyPI 上进行测试
      • 📦 发布到 PyPI
      • 🐳 构建并发布 Docker 镜像
      • 📝 创建带有更新日志的 GitHub 发布

  3. 设置（一次性）：

    # 显示设置说明
make setup-pypi

结果：

  • PyPI：uvx install teamspeak-mcp 可获取新版本
  • Docker：ghcr.io/marlburrow/teamspeak-mcp:v1.0.4 可用
  • GitHub：自动发布并带有更新日志
  • 无需手动操作！ 🎉

发布流程

本项目使用自动化的 GitHub Actions 来构建和发布 Docker 镜像：

  1. 标记发布：make release-patch（或 release-minor/release-major）
  2. 自动构建：GitHub Actions 构建并推送多架构镜像
  3. 随处可用：可在 PyPI、GitHub 容器注册表和 GitHub 发布中获取

🆘 故障排除

常见问题

  1. "连接被拒绝"

    • 检查服务器上的 ServerQuery 是否已启用
    • 验证端口（默认：10011）

  2. "身份验证失败"

    • 检查 ServerQuery 凭据
    • 确保用户具有适当的权限

  3. "未找到虚拟服务器"

    • 使用 serverlist 检查虚拟服务器 ID

  4. "Python 版本错误"

    • 确保使用的是 Python 3.10 - 3.12
    • MCP 库需要 Python 3.10 及以上版本

  5. "Docker 环境变量不起作用"

    • 在参数中使用 -e 标志，而不是 "env": {} 字段，以获得更好的兼容性
    • 确保在 Docker 参数中正确传递环境变量
    • 检查是否提供了所有必需的变量：TEAMSPEAK_HOST、TEAMSPEAK_USER、TEAMSPEAK_PASSWORD

日志

# 使用 Docker
docker logs container-name

# 不使用 Docker
python -m teamspeak_mcp.server --verbose

📄 许可证

MIT

默认排序 时间排序

0 个评论

« 上一篇
Didlogic
下一篇 »
Speech Interface (Faster Whisper)
  • 0 关注
  • 0 收藏，26 浏览
  • system 提出于 2025-10-03 06:36

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »