TeamSpeak MCP

一个用于通过AI模型（如Claude）控制TeamSpeak的Model Context Protocol (MCP) 服务器。

要求

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

功能

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

🎯 集成方法概述

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=yourn-user",
        "-e", "TEAMSPEAK_PASSWORD=your-password",
        "teamspeak-mcp"
      ]
    }
  }
}

🎯 应该选择哪种方法？

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

💡 快速开始示例

最快（PyPI）：

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

最可靠（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
# 添加到Claude Desktop配置中的Python模块

🚀 快速开始

自动安装脚本

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

在使用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连接到您的服务器：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交互：

基本命令

• "连接到TeamSpeak服务器"
• "向通用频道发送消息'大家好！'"
• "向用户5发送私信'你能加入我吗？'"
• "向用户12发送提醒消息'紧急：请查看公告！'"
• "列出连接的用户"
• "创建名为'Meeting'的临时频道"
• "将用户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操作“添加”
• "更改服务器名称为'My Gaming Server'并将最大客户端数设置为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_m_ mcp.py

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

Docker构建

# 构建
docker build -t teamspeak-mcp .

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

🔒 安全

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