Teamspeak MCP

🚀 TeamSpeak MCP

TeamSpeak MCP 是一個基於模型上下文協議（MCP）的服務器，可讓 Claude 等 AI 模型對 TeamSpeak 進行控制。藉助它，能夠實現從 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 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 服務器的憑據：

📋 所需信息

🔧 如何獲取憑據

步驟 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 用戶。切勿將管理員賬戶用於自動化工具。

💻 使用示例

基本命令

• "連接到 TeamSpeak 服務器"
• "向通用頻道發送消息 '大家好！'"
• "向用戶 5 發送私聊消息 '你能加入我嗎？'"
• "用消息 '緊急：請查看公告！' 戳用戶 12"
• "列出已連接的用戶"
• "創建一個名為 '會議' 的臨時頻道"
• "將用戶 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 並執行 "添加" 操作
• "將服務器名稱更改為 '我的遊戲服務器' 並將最大客戶端數設置為 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_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