Teamspeak MCP

🚀 TeamSpeak MCP

TeamSpeak MCPは、ClaudeのようなAIモデルからTeamSpeakを制御するためのModel Context Protocol (MCP)サーバーです。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/サイレントチャンネルの設定（トークパワーのプリセットを使用）
• 🎵 音声制御（ミュート、ミュート解除、キック、BAN）
• 🛡️ 細粒度のチャンネルごとの権限管理
• 🖥️ 仮想サーバーの設定（名前、説明、制限、ウェルカムメッセージ）
• 👥 ユーザー権限管理（サーバーグループ、個別の権限）
• 📊 包括的なサーバーとチャンネルの診断
• 📝 強化されたロギングシステム：
  • 自動ログ設定
  • ログ診断
  • インスタンスレベルのログ
  • 高度なフィルタリング
  • リアルタイム通知
• ⚙️ 39の強力なツールによる完全なTeamSpeak自動化

📦 インストール

必要条件

• Python 3.10 - 3.12
• Docker（コンテナ化されたデプロイメントの場合、オプション）
• ServerQueryが有効になっているTeamSpeak 3 Server

🎯 統合方法の概要

TeamSpeak MCPは、あなたのセットアップと好みに合わせた複数の統合方法を提供します。

📦 方法1: PyPIパッケージ（ほとんどのユーザーにおすすめ）

• ✅ 最も簡単なセットアップ - 1つのコマンドでインストール
• ✅ 標準的なパッケージマネージャーを通じた自動更新
• ✅ 標準的な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が動作する場所ならどこでも動作します

# インストール
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ユーザーを作成してください。自動化ツールに管理者アカウントを使用しないでください。

💻 使用例

基本的な使用法

設定が完了したら、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 : クライアントをBAN
• 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 : サーバーグループの権限を管理

🆕 モデレーションとBAN（合計3個）

• list_bans : サーバー上のすべてのアクティブなBANルールをリスト表示
• manage_ban_rules : BANルール（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つのコマンドでリリース:

   # パッチリリース (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 Container Registry、GitHub Releases

🆘 トラブルシューティング

一般的な問題

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 フラグを使用してください。
   • Docker引数で環境変数が正しく渡されていることを確認します。
   • すべての必要な変数が提供されていることを確認します: TEAMSPEAK_HOST、TEAMSPEAK_USER、TEAMSPEAK_PASSWORD

ログ

# Dockerの場合
docker logs container-name

# Dockerを使用しない場合
python -m teamspeak_mcp.server --verbose

📄 ライセンス

MIT