MarlBurroW/teamspeak-mcp

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

# Installation
uvx install teamspeak-mcp

# Usage
uvx teamspeak-mcp --host your-server.com --user your-user --password your-password

# Claude Desktop config (CLI args)
{
  "mcpServers": {
    "teamspeak": {
      "command": "uvx",
      "args": ["teamspeak-mcp", "--host", "your-server.com", "--user", "your-user", "--password", "your-password"]
    }
  }
}

🐳 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.

# Installation
docker pull ghcr.io/marlburrow/teamspeak-mcp:latest

# Claude Desktop config (env vars in args)
{
  "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"
      ]
    }
  }
}

🐍 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

# Installation
git clone https://github.com/MarlBurroW/teamspeak-mcp.git
cd teamspeak-mcp && pip install -r requirements.txt

# Claude Desktop config (Python module)
{
  "mcpServers": {
    "teamspeak": {
      "command": "python",
      "args": ["-m", "teamspeak_mcp.server", "--host", "your-server.com", "--user", "your-user", "--password", "your-password"]
    }
  }
}

🏗️ 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

# Installation
git clone https://github.com/MarlBurroW/teamspeak-mcp.git
cd teamspeak-mcp && docker build -t teamspeak-mcp .

# Claude Desktop config (local image)
{
  "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"
      ]
    }
  }
}

🎯 Which Method Should You Choose?

💡 Quick Start Examples

Fastest (PyPI):

uvx install teamspeak-mcp
# Add to Claude Desktop config with CLI args

Most Reliable (Docker):

docker pull ghcr.io/marlburrow/teamspeak-mcp:latest
# Add to Claude Desktop config with env vars in args

Most Flexible (Local):

git clone https://github.com/MarlBurroW/teamspeak-mcp.git
cd teamspeak-mcp && pip install -r requirements.txt
# Add to Claude Desktop config with Python module

🚀 Quick Start

Automatic installation script

python install.py

Connection test

python test_mcp.py

With Docker

# Build image
docker build -t teamspeak-mcp .

# Test with 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 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:

# Connect via telnet or putty to your-server:10011
telnet your-server.example.com 10011

# Login with admin
login serveradmin YOUR_ADMIN_PASSWORD

# Create dedicated user for MCP
serverqueryadd client_login_name=mcp_user client_login_password=secure_password123

# Grant necessary permissions (optional - adjust as needed)
servergroupaddclient sgid=6 cldbid=USER_DB_ID

Step 4: Test Connection

# Test with our connection script
python test_mcp.py

# Or with 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

💡 Quick Configuration Examples

For PyPI installation:

{
  "mcpServers": {
    "teamspeak": {
      "command": "uvx",
      "args": ["teamspeak-mcp", "--host", "your-server.example.com", "--user", "mcp_user", "--password", "secure_password123"]
    }
  }
}

For Docker installation:

{
  "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"
      ]
    }
  }
}

⚠️ 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

# Install development dependencies
pip install -r requirements.txt

# Run tests
python test_mcp.py

# Start MCP server
python -m teamspeak_mcp.server

Docker build

# Build
docker build -t teamspeak-mcp .

# Test
docker run --rm -it teamspeak-mcp

🔒 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

# With Docker
docker logs container-name

# Without Docker
python -m teamspeak_mcp.server --verbose

📝 License

MIT