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?

Use Case	Recommended Method	Why
First time user	PyPI Package (`uvx`)	Easiest setup, standard MCP pattern
Production deployment	Pre-built Docker	Reliable, versioned, no dependencies
CI/CD environments	Pre-built Docker	Consistent, fast deployment
Development/Contributing	Local Python	Full access to source code
Custom modifications	Local Docker Build	Controlled build process
Corporate environments	Local Docker Build	No external dependencies

💡 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

Parameter	Description	Example
TEAMSPEAK_HOST	Your server IP or domain	`ts.example.com` or `192.168.1.100`
TEAMSPEAK_PORT	ServerQuery port (default: 10011)	`10011`
TEAMSPEAK_USER	ServerQuery username	`mcp_user`
TEAMSPEAK_PASSWORD	ServerQuery password	`secure_password123`
TEAMSPEAK_SERVER_ID	Virtual server ID (usually 1)	`1`

🔧 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:

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

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

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:

Tag a release: make release-patch (or release-minor/release-major)
Automatic build: GitHub Actions builds and pushes multi-arch images
Available everywhere: PyPI, GitHub Container Registry, and GitHub Releases

🆘 Troubleshooting

Common Issues

"Connection refused"
- Check that ServerQuery is enabled on your server
- Verify port (default: 10011)
"Authentication failed"
- Check your ServerQuery credentials
- Ensure user has proper permissions
"Virtual server not found"
- Check virtual server ID with serverlist
"Python version error"
- Ensure you're using Python 3.10-3.12
- The MCP library requires Python 3.10+
"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