shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

teamspeak-mcp

TeamSpeak MCP是一个基于Model Context Protocol的服务，用于通过AI模型（如Claude）控制TeamSpeak服务器，提供全面的频道管理、用户权限控制、语音调节等功能。

article

README

🚀 TeamSpeak MCP

TeamSpeak MCP 是一个基于模型上下文协议（MCP）的服务器，可让 Claude 等 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 配置中

💻 使用示例

基础用法

使用 Claude 控制 TeamSpeak MCP 的基本命令如下：

# 连接到 TeamSpeak 服务器
"Connect to TeamSpeak server"
# 向通用频道发送消息
"Send message 'Hello everyone!' to general channel"
# 向用户 5 发送私人消息
"Send private message 'Can you join me?' to user 5"
# 向用户 12 发送戳消息
"Poke user 12 with message 'Urgent: Please check the announcement!'"
# 列出已连接的用户
"List connected users"
# 创建名为 'Meeting' 的临时频道
"Create temporary channel called 'Meeting'"
# 将用户 John 移动到私人频道
"Move user John to private channel"
# 显示服务器信息
"Show me server info"

高级用法

使用 Claude 控制 TeamSpeak MCP 的高级命令如下：

# 将频道 5 设置为静音，禁止任何人发言
"Make channel 5 silent so nobody can talk" 
# 设置一个受管理的欢迎频道
"Set up a moderated welcome channel" 
# 更新频道 3，将最大客户端数设置为 10 并添加密码 'secret'
"Update channel 3 to set max clients to 10 and add password 'secret'" 
# 显示频道 7 的详细信息
"Show me detailed information about channel 7" 
# 获取客户端 12 的全面详细信息
"Get comprehensive details about client 12" 
# 列出频道 4 的所有权限
"List all permissions for channel 4" 
# 为频道 6 添加发言权限
"Add talk power permission to channel 6" 
# 将服务器名称更改为 'My Gaming Server' 并将最大客户端数设置为 100
"Change server name to 'My Gaming Server' and set max clients to 100" 
# 设置欢迎消息为 'Welcome to our server!'
"Set welcome message to 'Welcome to our server!'" 
# 将用户 15 添加到管理员组 6
"Add user 15 to admin group 6" 
# 将用户 8 从管理员组中移除
"Remove user 8 from moderator group" 
# 显示用户 12 的所有服务器组
"Show all server groups for user 12" 
# 为用户 20 授予 'b_client_kick' 权限，值为 75
"Give user 20 the 'b_client_kick' permission with value 75" 
# 诊断当前权限和连接情况
"Diagnose my current permissions and connection" 
# 检查无法列出客户端的原因
"Check why I can't list clients"

📚 详细文档

🔑 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 用户。切勿将管理员账户用于自动化工具。

🔧 技术细节

🎯 可用工具（共 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 : 管理服务器组的权限

🆕 moderation & 封禁管理（共 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

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端