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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A Model Context Protocol server that enables AI models like Claude to control TeamSpeak servers, allowing users to manage channels, send messages, configure permissions, and perform server administration through natural language commands.

Related MCP Servers

API Tester MCP Server
Vikrant-Khedkar
-
security
F
license
-
quality
A Model Context Protocol server that allows Claude to make API requests on your behalf, providing tools for testing various APIs including HTTP requests and OpenAI integrations without sharing your API keys in the chat.
Last updated -
Python
MCP Python Toolbox
gianlucamazza
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants like Claude to perform Python development tasks through file operations, code analysis, project management, and safe code execution.
Last updated -
1
Python
TTS-MCP
nakamurau1
-
security
A
license
-
quality
A Model Context Protocol server that integrates high-quality text-to-speech capabilities with Claude Desktop and other MCP-compatible clients, supporting multiple voice options and audio formats.
Last updated -
TypeScript
MIT License
Filesystem MCP Server
QuantGeekDev
-
security
F
license
-
quality
A Model Context Protocol server that extends AI capabilities by providing file system access and management functionalities to Claude or other AI assistants.
Last updated -
3
TypeScript

View all related MCP servers