TeamSpeak MCP

A Model Context Protocol (MCP) server for controlling TeamSpeak from AI models like Claude.

Requirements

• Python 3.10-3.12

• Docker (optional, for containerized deployment)

• TeamSpeak 3 Server with ServerQuery enabled

Features

• 🎯 Connect to TeamSpeak servers

• 💬 Send messages to channels, private messages, and pokes (alert notifications)

• 📋 List connected users and detailed client information

• 🔧 Advanced channel management (create, delete, update properties, permissions)

• 🔇 AFK/Silent channel setup with talk power presets

• 🎵 Voice control (mute, unmute, kick, ban)

• 🛡️ Fine-grained permission management per channel

• 🖥️ Virtual server configuration (name, description, limits, welcome messages)

• 👥 User permission management (server groups, individual permissions)

• 📊 Comprehensive server and channel diagnostics

• 📝 Enhanced logging system with:

  • Automatic log configuration

  • Log diagnostics

  • Instance-level logs

  • Advanced filtering

  • Real-time notifications

• ⚙️ 39 powerful tools for complete TeamSpeak automation

🎯 Integration Methods Overview

TeamSpeak MCP offers multiple integration methods to fit your setup and preferences:

📦 Method 1: PyPI Package (Recommended for most users)

• ✅ Easiest setup - One command installation

• ✅ Automatic updates via standard package managers

• ✅ Standard MCP pattern - Compatible with Claude Desktop examples

• ✅ No Docker required - Pure Python implementation

🐳 Method 2: Pre-built Docker Images (Recommended for containers)

• ✅ No dependencies - Everything included

• ✅ Version consistency - Immutable deployments

• ✅ Easy scaling - Works with orchestration

• ✅ Cross-platform - Works anywhere Docker runs

💡 Note: We use -e flags in args instead of the "env": {} field because Claude Desktop's environment variable handling can be unreliable. The args method ensures consistent variable passing.

🐍 Method 3: Local Python Installation (For developers)

• ✅ Full control - Access to source code

• ✅ Customizable - Modify for specific needs

• ✅ Development - Contribute to the project

• ⚠️ More setup - Requires Python environment management

🏗️ Method 4: Local Docker Build (For customization)

• ✅ Custom builds - Modify Dockerfile as needed

• ✅ Offline capability - No external dependencies

• ✅ Version control - Pin to specific commits

• ⚠️ Build time - Requires local Docker build

🎯 Which Method Should You Choose?

💡 Quick Start Examples

Fastest (PyPI):

Most Reliable (Docker):

Most Flexible (Local):

🚀 Quick Start

Automatic installation script

Connection test

With Docker

🔑 TeamSpeak Server Setup

Before using TeamSpeak MCP, you need to configure your TeamSpeak server credentials:

📋 Required Information

🔧 How to Get Your Credentials

Step 1: Enable ServerQuery

On your TeamSpeak server, ensure ServerQuery is enabled:

• Check ts3server.ini: query_port=10011

• Default enabled on most installations

Step 2: Get Admin Access

• First installation: Check server logs for admin token: token=AAAA...

• Existing server: Use your admin credentials

Step 3: Create MCP User

Connect to ServerQuery and create a dedicated user:

Step 4: Test Connection

💡 Quick Configuration Examples

For PyPI installation:

For Docker installation:

⚠️ Security Note: Create a dedicated ServerQuery user with minimal permissions. Never use your admin account for automated tools.

Usage

Once configured, you can use these commands with Claude:

Basic Commands

• "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"

🆕 Advanced Commands

• "Make channel 5 silent so nobody can talk" → Uses set_channel_talk_power with preset "silent"

• "Set up a moderated welcome channel" → Uses set_channel_talk_power with preset "moderated"

• "Update channel 3 to set max clients to 10 and add password 'secret'" → Uses update_channel

• "Show me detailed information about channel 7" → Uses channel_info

• "Get comprehensive details about client 12" → Uses client_info_detailed

• "List all permissions for channel 4" → Uses manage_channel_permissions with action "list"

• "Add talk power permission to channel 6" → Uses manage_channel_permissions with action "add"

• "Change server name to 'My Gaming Server' and set max clients to 100" → Uses update_server_settings

• "Set welcome message to 'Welcome to our server!'" → Uses update_server_settings

• "Add user 15 to admin group 6" → Uses manage_user_permissions with action "add_group"

• "Remove user 8 from moderator group" → Uses manage_user_permissions with action "remove_group"

• "Show all server groups for user 12" → Uses manage_user_permissions with action "list_groups"

• "Give user 20 the 'b_client_kick' permission with value 75" → Uses manage_user_permissions with action "add_permission"

• "Diagnose my current permissions and connection" → Uses diagnose_permissions

• "Check why I can't list clients" → Uses diagnose_permissions

🎯 Available Tools (39 total)

Core Tools (12 total)

• connect_to_server : Connect to TeamSpeak server

• send_channel_message : Send message to a channel

• send_private_message : Send private message

• poke_client : Send poke (alert notification) to a user - more attention-grabbing than private message

• list_clients : List connected clients

• list_channels : List channels

• create_channel : Create new channel

• delete_channel : Delete channel

• move_client : Move client to another channel

• kick_client : Kick client

• ban_client : Ban client

• server_info : Get server information

🆕 Advanced Management Tools (8 total)

• update_channel : Update channel properties (name, description, password, talk power, limits, etc.)

• set_channel_talk_power : Quick setup for AFK/silent/moderated channels with presets

• channel_info : Get detailed channel information (permissions, codec, type, etc.)

• manage_channel_permissions : Fine-grained permission control (add/remove/list)

• client_info_detailed : Comprehensive client details (platform, version, status, etc.)

• update_server_settings : Update virtual server settings (name, welcome message, max clients, password, host message, default groups)

• manage_user_permissions : Complete user permission management (add/remove server groups, set individual permissions, list assignments)

• diagnose_permissions : Diagnose current connection permissions and troubleshoot issues

🆕 Server Groups Management (4 total)

• list_server_groups : List all server groups available

• assign_client_to_group : Add or remove clients from server groups

• create_server_group : Create new server groups with custom settings

• manage_server_group_permissions : Manage permissions for server groups

🆕 Moderation & Bans (3 total)

• list_bans : List all active ban rules on the server

• manage_ban_rules : Create, delete or manage ban rules (IP, name, UID-based)

• list_complaints : List complaints against users

🆕 Search & Discovery (2 total)

• search_clients : Search for clients by name pattern or unique identifier

• find_channels : Search for channels by name pattern

🆕 Privilege Tokens (2 total)

• list_privilege_tokens : List all privilege keys/tokens available

• create_privilege_token : Create new privilege tokens for server/channel access

🆕 File Management (3 total)

• list_files : List files in a channel's file repository

• get_file_info : Get detailed information about specific files

• manage_file_permissions : List and manage active file transfers

🆕 Logs & Monitoring (3 total)

• view_server_logs : View recent entries from the server log

• add_log_entry : Add custom entries to the server log

• get_connection_info : Get detailed connection information

🆕 Snapshots & Backup (2 total)

• create_server_snapshot : Create snapshots of server configuration

• deploy_server_snapshot : Deploy/restore server configuration from snapshots

🔧 Development

Local testing

Docker build

🔒 Security

• 🔑 Never commit credentials in code

• 🛡️ Use ServerQuery accounts with limited privileges

• 🌐 Configure firewall to restrict ServerQuery port access

• 🔄 Change ServerQuery passwords regularly

🚀 Automatized Release Workflow (For Maintainers)

This project uses fully automated releases via GitHub Actions. No manual PyPI uploads needed!

How it works:

1. One Command Release:

   # Patch release (1.0.3 -> 1.0.4) make release-patch # Minor release (1.0.3 -> 1.1.0) make release-minor # Major release (1.0.3 -> 2.0.0) make release-major

2. Automatic Process:

   • ✅ Bumps version in pyproject.toml

   • ✅ Creates git commit and tag

   • ✅ Pushes to GitHub

   • ✅ GitHub Actions triggers automatically:

     • 🔨 Builds Python package

     • 🧪 Tests on TestPyPI first

     • 📦 Publishes to PyPI

     • 🐳 Builds and publishes Docker images

     • 📝 Creates GitHub release with changelog

3. Setup (One-time):

   # Show setup instructions make setup-pypi

Result:

• PyPI: uvx install teamspeak-mcp gets the new version

• Docker: ghcr.io/marlburrow/teamspeak-mcp:v1.0.4 available

• GitHub: Automatic release with changelog

• No manual work needed! 🎉

📦 Release Process

This project uses automated GitHub Actions for building and publishing Docker images:

1. Tag a release: make release-patch (or release-minor/release-major)

2. Automatic build: GitHub Actions builds and pushes multi-arch images

3. Available everywhere: PyPI, GitHub Container Registry, and GitHub Releases

🆘 Troubleshooting

Common Issues

1. "Connection refused"

   • Check that ServerQuery is enabled on your server

   • Verify port (default: 10011)

2. "Authentication failed"

   • Check your ServerQuery credentials

   • Ensure user has proper permissions

3. "Virtual server not found"

   • Check virtual server ID with serverlist

4. "Python version error"

   • Ensure you're using Python 3.10-3.12

   • The MCP library requires Python 3.10+

5. "Docker environment variables not working"

   • Use -e flags in args instead of the "env": {} field for better compatibility

   • Ensure environment variables are passed correctly in Docker args

   • Check that all required variables are provided: TEAMSPEAK_HOST, TEAMSPEAK_USER, TEAMSPEAK_PASSWORD

Logs

📝 License

MIT