Teamspeak MCP

🚀 TeamSpeak MCP

TeamSpeak MCP 是一个基于模型上下文协议（MCP）的服务器，用于让像 Claude 这样的 AI 模型控制 TeamSpeak。它提供了丰富的功能，能够高效地管理 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 用户。切勿将管理员账户用于自动化工具。

💻 使用示例

基础用法

配置完成后，你可以使用以下命令与 Claude 配合使用：

• "Connect to TeamSpeak server"
• "Send message 'Hello everyone!' to general channel"
• "Send private message 'Can you join me?' to user 5"
• "Poke user 12 with message 'Urgent: Please check the announcement!'"
• "List connected users"
• "Create temporary channel called 'Meeting'"
• "Move user John to private channel"
• "Show me server info"

高级用法

• "Make channel 5 silent so nobody can talk" → 使用 set_channel_talk_power 预设 "silent"
• "Set up a moderated welcome channel" → 使用 set_channel_talk_power 预设 "moderated"
• "Update channel 3 to set max clients to 10 and add password 'secret'" → 使用 update_channel
• "Show me detailed information about channel 7" → 使用 channel_info
• "Get comprehensive details about client 12" → 使用 client_info_detailed
• "List all permissions for channel 4" → 使用 manage_channel_permissions 操作 "list"
• "Add talk power permission to channel 6" → 使用 manage_channel_permissions 操作 "add"
• "Change server name to 'My Gaming Server' and set max clients to 100" → 使用 update_server_settings
• "Set welcome message to 'Welcome to our server!'" → 使用 update_server_settings
• "Add user 15 to admin group 6" → 使用 manage_user_permissions 操作 "add_group"
• "Remove user 8 from moderator group" → 使用 manage_user_permissions 操作 "remove_group"
• "Show all server groups for user 12" → 使用 manage_user_permissions 操作 "list_groups"
• "Give user 20 the 'b_client_kick' permission with value 75" → 使用 manage_user_permissions 操作 "add_permission"
• "Diagnose my current permissions and connection" → 使用 diagnose_permissions
• "Check why I can't list clients" → 使用 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. "Connection refused"

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

2. "Authentication failed"

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

3. "Virtual server not found"

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

4. "Python version error"

   • 确保使用的是 Python 3.10 - 3.12
   • MCP 库需要 Python 3.10+

5. "Docker environment variables not working"

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

日志

# 使用 Docker
docker logs container-name

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

📄 许可证

MIT