TeamSpeak

TeamSpeak MCP lets you control TeamSpeak servers and automate common administrative tasks from AI-powered workflows. By connecting to a TeamSpeak ServerQuery-enabled server, you can send messages, manage channels and users, retrieve diagnostics, and set up advanced permissions and automation tools to streamline server administration.

How to use

You operate the MCP server by choosing a client method that fits your deployment style, then configure your client with the host, credentials, and a start command. Once configured, you can perform actions like sending messages to channels, listing connected users, creating or updating channels, and adjusting server settings. You can also leverage advanced tools to manage permissions, diagnose connection issues, and automate routine maintenance.

Typical workflows include authenticating against a TeamSpeak ServerQuery account with restricted privileges, starting the MCP client, and issuing high‑level commands through your automation tool or Claude Desktop style interface. For example, you can create or modify channels, mute or kick users, update server properties, and inspect detailed client or channel information. Use the rich toolset to implement your server policies, moderation workflows, and automated diagnostics.

How to install

Follow these steps to install or run an MCP server instance using your preferred method. Prerequisites include Python 3.10–3.12, Docker if you plan to run containerized deployments, and a TeamSpeak 3 Server with ServerQuery enabled.

# Prerequisites: ensure Python is installed
python --version

# Optional: install Docker if you plan to use containers
docker --version

Choose one of the supported integration methods below and follow the exact steps to start using MCP with your TeamSpeak server.

Method 1 — PyPI Package (Recommended for most users)

# 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)

# 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)

# 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)

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

Configuration notes and security

Create a dedicated ServerQuery user with restricted permissions and avoid using your admin credentials for automated tasks. When using Docker, pass credentials as environment variables in the command line to ensure they are not exposed in code.

A final connection test helps verify that MCP can reach TeamSpeak ServerQuery and perform basic operations. Use the provided test procedure for your chosen method to confirm connectivity and permissions.

Troubleshooting

If you encounter connection issues, verify that ServerQuery is enabled on your TeamSpeak server and that the credentials and server ID are correct. Check the ServerQuery port (default 10011) and ensure the host is reachable from your deployment environment.

For authentication problems, confirm that the ServerQuery user has the necessary permissions and that its password is up to date. If you see a virtual server not found error, double-check the virtual server ID with a server list command.

If environment variables do not propagate in Docker, prefer passing credentials via -e flags in the run command to ensure compatibility with your Claude Desktop setup.

Available tools

connect_to_server

Establish a connection to the TeamSpeak server via ServerQuery.

send_channel_message

Post a message to a specific channel.

send_private_message

Send a private message to a user.

poke_client

Send a poke/alert notification to a user.

list_clients

List currently connected clients with details.

list_channels

List all channels on the server.

create_channel

Create a new channel with specified properties.

delete_channel

Delete a channel by ID.

move_client

Move a client to a different channel.

kick_client

Kick a client from the server.

ban_client

Ban a client from the server.

server_info

Retrieve general server information.

update_channel

Modify channel properties such as name, description, persistence, and permissions.

set_channel_talk_power

Configure AFK/silent/moderated talk power presets on a channel.

channel_info

Get detailed information about a channel and its permissions.

manage_channel_permissions

List, add, or remove permissions for a channel.

client_info_detailed

Fetch comprehensive details about a client.

update_server_settings

Update virtual server settings like name, welcome message, and limits.

manage_user_permissions

Manage server groups and individual user permissions.

diagnose_permissions

Diagnose current permissions and connection status.

list_server_groups

List all server groups.

assign_client_to_group

Add or remove a client from a server group.

create_server_group

Create a new server group with custom permissions.

manage_server_group_permissions

Manage permissions assigned to a server group.

list_bans

Show all active ban rules on the server.

manage_ban_rules

Create, delete, or manage ban rules.

list_complaints

List complaints against users.

search_clients

Search for clients by name or identifier.

find_channels

Search for channels by name.

list_privilege_tokens

List available privilege tokens.

create_privilege_token

Create new privilege tokens.

list_files

List files in a channel's repository.

get_file_info

Get detailed information about a file.

manage_file_permissions

Manage active file transfers and permissions.

view_server_logs

Display recent server log entries.

add_log_entry

Append a custom log entry to the server log.

get_connection_info

Retrieve detailed connection information.

create_server_snapshot

Create a snapshot of server configuration.

deploy_server_snapshot

Deploy or restore server configuration from a snapshot.