Teamspeak MCP

🚀 TeamSpeak MCP

このプロジェクトは、ClaudeのようなAIモデルからTeamSpeakを制御するためのModel Context Protocol (MCP) サーバーです。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/サイレントチャンネルの設定
• 🎵 音声制御（ミュート、ミュート解除、キック、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が動作する場所ならどこでも動作

⚠️ 重要提示

Claude Desktopの環境変数の扱いは信頼性が低い場合があるため、"env": {}フィールドではなく-eフラグを引数で使用します。引数を使用する方法では、変数の渡し方が一貫します。

# インストール
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: 変更履歴付きの自動リリースが行われます。
• 手動作業は不要です！ 🎉

📦 リリースプロセス

このプロジェクトでは、Dockerイメージのビルドと公開に自動化されたGitHub Actionsを使用しています。

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"

   • 互換性を高めるために、"env": {}フィールドではなく-eフラグを引数で使用します。
   • Dockerの引数で環境変数が正しく渡されていることを確認します。
   • すべての必要な変数（TEAMSPEAK_HOST、TEAMSPEAK_USER、TEAMSPEAK_PASSWORD）が提供されていることを確認します。

ログ

# Dockerを使用する場合
docker logs container-name

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

📄 ライセンス

MIT