teamspeak-mcp

🚀 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