Teamspeak MCP

🚀 TeamSpeak MCP

TeamSpeak MCP 是一個基於模型上下文協議（MCP）的服務器，用於讓像 Claude 這樣的 AI 模型控制 TeamSpeak。它提供了豐富的功能，能夠高效地管理 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 配置

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

💻 使用示例

基礎用法

配置完成後，你可以使用以下命令與 Claude 配合使用：

• "Connect to TeamSpeak server"
• "Send message 'Hello everyone!' to general channel"
• "Send private message 'Can you join me?' to user 5"
• "Poke user 12 with message 'Urgent: Please check the announcement!'"
• "List connected users"
• "Create temporary channel called 'Meeting'"
• "Move user John to private channel"
• "Show me server info"

高級用法

• "Make channel 5 silent so nobody can talk" → 使用 set_channel_talk_power 預設 "silent"
• "Set up a moderated welcome channel" → 使用 set_channel_talk_power 預設 "moderated"
• "Update channel 3 to set max clients to 10 and add password 'secret'" → 使用 update_channel
• "Show me detailed information about channel 7" → 使用 channel_info
• "Get comprehensive details about client 12" → 使用 client_info_detailed
• "List all permissions for channel 4" → 使用 manage_channel_permissions 操作 "list"
• "Add talk power permission to channel 6" → 使用 manage_channel_permissions 操作 "add"
• "Change server name to 'My Gaming Server' and set max clients to 100" → 使用 update_server_settings
• "Set welcome message to 'Welcome to our server!'" → 使用 update_server_settings
• "Add user 15 to admin group 6" → 使用 manage_user_permissions 操作 "add_group"
• "Remove user 8 from moderator group" → 使用 manage_user_permissions 操作 "remove_group"
• "Show all server groups for user 12" → 使用 manage_user_permissions 操作 "list_groups"
• "Give user 20 the 'b_client_kick' permission with value 75" → 使用 manage_user_permissions 操作 "add_permission"
• "Diagnose my current permissions and connection" → 使用 diagnose_permissions
• "Check why I can't list clients" → 使用 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. "Connection refused"

   • 檢查服務器上的 ServerQuery 是否已啟用
   • 驗證端口（默認：10011）

2. "Authentication failed"

   • 檢查 ServerQuery 憑據
   • 確保用戶具有適當的權限

3. "Virtual server not found"

   • 使用 serverlist 檢查虛擬服務器 ID

4. "Python version error"

   • 確保使用的是 Python 3.10 - 3.12
   • MCP 庫需要 Python 3.10+

5. "Docker environment variables not working"

   • 在參數中使用 -e 標誌，而不是 "env": {} 字段，以獲得更好的兼容性
   • 確保在 Docker 參數中正確傳遞環境變量
   • 檢查是否提供了所有必需的變量：TEAMSPEAK_HOST、TEAMSPEAK_USER、TEAMSPEAK_PASSWORD

日誌

# 使用 Docker
docker logs container-name

# 不使用 Docker
python -m teamspeak_mcp.server --verbose

📄 許可證

MIT