团队语音-mcp

Name: 团队语音-mcp
Author: MarlBurroW

作者：MarlBurroW7 星标更新：2025-06-08

安装使用来源：spider==github.com

项目介绍

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端口的访问
🔄