TeamSpeak MCP server

TeamSpeak MCP is a server implementation of the Model Context Protocol (MCP) that allows AI models like Claude to control TeamSpeak servers. It provides a comprehensive set of tools for managing channels, users, permissions, and server settings through simple natural language commands.

Installation Options

PyPI Package (Recommended)

The easiest way to install TeamSpeak MCP is using the PyPI package:

uvx install teamspeak-mcp

To use it with Claude Desktop, add this configuration:

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

Docker Container

For containerized deployment:

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

Claude Desktop configuration with Docker:

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

Local Python Installation

For developers who want full control:

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

Claude Desktop configuration with local Python:

{
  "mcpServers": {
    "teamspeak": {
      "command": "python",
      "args": ["-m", "teamspeak_mcp.server", "--host", "your-server.com", "--user", "your-user", "--password", "your-password"]
    }
  }
}

Local Docker Build

For customization and offline capability:

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

Claude Desktop configuration with local Docker build:

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

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

Creating a ServerQuery 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

Testing Connection

# With PyPI installation
uvx teamspeak-mcp test --host your-server.com --user your-user --password your-password

# 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

Usage Examples

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"
• "Set up a moderated welcome channel"
• "Update channel 3 to set max clients to 10 and add password 'secret'"
• "Show me detailed information about channel 7"
• "Get comprehensive details about client 12"
• "List all permissions for channel 4"
• "Add talk power permission to channel 6"
• "Change server name to 'My Gaming Server' and set max clients to 100"
• "Set welcome message to 'Welcome to our server!'"
• "Add user 15 to admin group 6"
• "Remove user 8 from moderator group"
• "Show all server groups for user 12"
• "Give user 20 the 'b_client_kick' permission with value 75"
• "Diagnose my current permissions and connection"

Available Tools

Core Tools

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

• update_channel: Update channel properties
• set_channel_talk_power: Quick setup for AFK/silent/moderated channels
• channel_info: Get detailed channel information
• manage_channel_permissions: Fine-grained permission control
• client_info_detailed: Comprehensive client details
• update_server_settings: Update virtual server settings
• manage_user_permissions: Complete user permission management
• diagnose_permissions: Diagnose current connection permissions

Server Groups Management

• list_server_groups: List all server groups
• assign_client_to_group: Add or remove clients from server groups
• create_server_group: Create new server groups
• manage_server_group_permissions: Manage permissions for server groups

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

5. "Docker environment variables not working"

   • Use -e flags in args instead of the "env": {} field
   • Ensure all required variables are provided

Enabling Verbose Logging

# With Docker
docker run --rm -it \
  -e TEAMSPEAK_HOST=your-server.com \
  -e TEAMSPEAK_USER=your-user \
  -e TEAMSPEAK_PASSWORD=your-password \
  ghcr.io/marlburrow/teamspeak-mcp:latest --verbose

# With PyPI
uvx teamspeak-mcp --host your-server.com --user your-user --password your-password --verbose

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "teamspeak" '{"command":"uvx","args":["teamspeak-mcp","--host","your-server.com","--user","your-user","--password","your-password"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect