TeamSpeak MCP

TeamSpeak MCP

用于从Claude等AI模型控制TeamSpeak的模型上下文协议（MCP）服务器。

需求

• Python 3.10-3.12
• 码头工人 （可选，用于容器化部署）
• TeamSpeak 3服务器 启用ServerQuery

特性

• 🎯 连接到TeamSpeak服务器
• 💬 向频道发送消息、私人消息和pokes（警报通知）
• 📋 列出已连接的用户和详细的客户端信息
• 🔧 高级渠道管理 （创建、删除、更新属性、权限）
• 🔇 AFK/静音频道设置 具有通话功率预设
• 🎵 语音控制（静音、取消静音、踢腿、禁止）
• 🛡️ 细粒度权限管理 每个频道
• 🖥️ 虚拟服务器配置 （名称、描述、限制、欢迎消息）
• 👥 用户权限管理 （服务器组、个人权限）
• 📊 全面的服务器和通道诊断
• 📝 增强型测井系统 与：

- 自动日志配置 - 日志诊断 - 实例级日志 - 高级过滤 - 实时通知

• ⚙️ 39个强大的工具 实现完整的TeamSpeak自动化

🎯 集成方法概述

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

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

• ✅ 最简单的设置 -一个命令安装
• ✅ 自动更新 通过标准包管理器
• ✅ 标准MCP模式 -与Claude Desktop示例兼容
• ✅ 无需Docker -纯Python实现

# Installation
uvx install teamspeak-mcp

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

# Claude Desktop config (CLI args)
{
  "mcpServers": {
    "teamspeak": {
      "command": "uvx",
      "args": ["teamspeak-mcp", "--host", "your-server.com", "--user", "your-user", "--password", "your-password"]
    }
  }
}

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

• ✅ 无依赖关系 -一切都包括在内
• ✅ 版本一致性 -不可变部署
• ✅ 易于扩展 -与编排配合使用
• ✅ 跨平台 -适用于Docker运行的任何地方

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

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

# Claude Desktop config (env vars in args)
{
  "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环境管理

# Installation
git clone https://github.com/MarlBurroW/teamspeak-mcp.git
cd teamspeak-mcp && pip install -r requirements.txt

# Claude Desktop config (Python module)
{
  "mcpServers": {
    "teamspeak": {
      "command": "python",
      "args": ["-m", "teamspeak_mcp.server", "--host", "your-server.com", "--user", "your-user", "--password", "your-password"]
    }
  }
}

🏗️ 方法4：本地Docker构建（用于定制）

• ✅ 自定义构建 -根据需要修改Dockerfile
• ✅ 离线能力 -无外部依赖关系
• ✅ 版本控制 -固定到特定提交
• ⚠️ 构建时间 -需要本地Docker构建

# Installation
git clone https://github.com/MarlBurroW/teamspeak-mcp.git
cd teamspeak-mcp && docker build -t teamspeak-mcp .

# Claude Desktop config (local image)
{
  "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 install teamspeak-mcp
# Add to Claude Desktop config with CLI args

最可靠（Docker）：

docker pull ghcr.io/marlburrow/teamspeak-mcp:latest
# Add to Claude Desktop config with env vars in args

最灵活（本地）：

git clone https://github.com/MarlBurroW/teamspeak-mcp.git
cd teamspeak-mcp && pip install -r requirements.txt
# Add to Claude Desktop config with Python module

🚀 快速开始

自动安装脚本

python install.py

连接测试

python test_mcp.py

使用Docker

# Build image
docker build -t teamspeak-mcp .

# Test with 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服务器设置

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

📋 所需信息

🔧 如何获取您的证书

步骤1：启用ServerQuery

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

• 检查 ts3server.ini: query_port=10011
• 大多数安装都启用了默认设置

步骤2：获取管理员权限

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

步骤3：创建MCP用户

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

# Connect via telnet or putty to your-server:10011
telnet your-server.example.com 10011

# Login with admin
login serveradmin YOUR_ADMIN_PASSWORD

# Create dedicated user for MCP
serverqueryadd client_login_name=mcp_user client_login_password=secure_password123

# Grant necessary permissions (optional - adjust as needed)
servergroupaddclient sgid=6 cldbid=USER_DB_ID

步骤4：测试连接

# Test with our connection script
python test_mcp.py

# Or with 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中使用这些命令：

基本命令

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

🆕 高级命令

• *“让第5频道静音，这样就没有人能说话了”* → Uses set_channel_talk_power 预设为“静音”
• *“设置一个有主持人的欢迎频道”* → Uses set_channel_talk_power 预设“已审核”
• *“更新通道3，将最大客户端数设置为10，并添加密码‘secret’”* → Uses update_channel
• *“显示频道7的详细信息”* → Uses channel_info
• *“获取有关客户12的全面详细信息”* → Uses client_info_detailed
• *“列出频道4的所有权限”* → Uses manage_channel_permissions 带动作“列表”
• *“为频道6添加通话权限”* → Uses manage_channel_permissions 使用“添加”操作
• *“将服务器名称更改为“我的游戏服务器”，并将最大客户端数设置为100”* → Uses update_server_settings
• *“将欢迎消息设置为‘欢迎使用我们的服务器！’”* → Uses update_server_settings
• *“将用户15添加到管理员组6”* → Uses manage_user_permissions 使用操作“add_group”
• *“从主持人组中删除用户8”* → Uses manage_user_permissions 使用“remove_group”操作
• *“显示用户12的所有服务器组”* → Uses manage_user_permissions 使用“list_groups”操作
• *“将值为75的'b_client_ick'权限授予用户20”* → Uses manage_user_permissions 使用“add_permission”操作
• *“诊断我当前的权限和连接”* → Uses diagnose_permissions
• *“检查我为什么不能列出客户”* → Uses diagnose_permissions

🎯 可用工具（共39个）

核心工具（共12个）

• connect_to_server ：连接到TeamSpeak服务器
• send_channel_message ：向频道发送消息
• send_private_message ：发送私人消息
• poke_client ：向用户发送poke（警报通知）-比私信更引人注目
• list_clients ：列出已连接的客户端
• list_channels ：列出频道
• create_channel ：创建新频道
• delete_channel ：删除频道
• move_client ：将客户端移动到另一个频道
• kick_client ：Kick客户端
• 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 ：从快照部署/还原服务器配置

🔧 发展

局部测试

# Install development dependencies
pip install -r requirements.txt

# Run tests
python test_mcp.py

# Start MCP server
python -m teamspeak_mcp.server

Docker构建

# Build
docker build -t teamspeak-mcp .

# Test
docker run --rm -it teamspeak-mcp

🔒 安全

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

🚀 自动化发布工作流程（适用于维护人员）

此项目使用 全自动发布 通过GitHub操作。无需手动上传PyPI！

它是如何工作的：

1. 一个命令发布：

   # Patch release (1.0.3 -> 1.0.4)
   make release-patch

   # Minor release (1.0.3 -> 1.1.0) 
   make release-minor

   # Major release (1.0.3 -> 2.0.0)
   make release-major

1. 自动过程：

- ✅ 凹凸版本 pyproject.toml - ✅ 创建git commit和tag - ✅ 推送到GitHub - ✅ GitHub操作会自动触发： - 🔨 构建Python包 - 🧪 首先在TestPyPI上进行测试 - 📦 发布到PyPI - 🐳 构建并发布Docker镜像 - 📝 使用changelog创建GitHub版本

1. 设置（一次性）：

   # Show setup instructions
   make setup-pypi

结果：

• PyPI: uvx install teamspeak-mcp 获取新版本
• 码头工人: 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）

1. “身份验证失败”

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

1. “找不到虚拟服务器”

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

1. “Python版本错误”

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

1. “Docker环境变量不起作用”

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

日志

# With Docker
docker logs container-name

# Without Docker
python -m teamspeak_mcp.server --verbose

📝 许可证

麻省理工学院