https://github.com/marlburrow/teamspeak-mcp
A Model Context Protocol (MCP) server for controlling TeamSpeak from AI models like Claude
https://github.com/marlburrow/teamspeak-mcp
Last synced: 3 months ago
JSON representation
A Model Context Protocol (MCP) server for controlling TeamSpeak from AI models like Claude
- Host: GitHub
- URL: https://github.com/marlburrow/teamspeak-mcp
- Owner: MarlBurroW
- License: mit
- Created: 2025-06-06T10:29:31.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-06-06T11:27:13.000Z (4 months ago)
- Last Synced: 2025-06-06T11:31:06.663Z (4 months ago)
- Language: Python
- Size: 27.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TeamSpeak MCP
[](https://badge.fury.io/py/teamspeak-mcp)
[](https://pypi.org/project/teamspeak-mcp/)
[](https://modelcontextprotocol.io)
[](https://github.com/MarlBurroW/teamspeak-mcp/actions)
[](https://github.com/MarlBurroW/teamspeak-mcp/pkgs/container/teamspeak-mcp)
[](https://github.com/MarlBurroW/teamspeak-mcp/blob/main/LICENSE)
[](https://github.com/MarlBurroW/teamspeak-mcp/stargazers)
[](https://github.com/MarlBurroW/teamspeak-mcp/issues)
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
```bash
# 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.
```bash
# 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
```bash
# 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
```bash
# 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):**
```bash
uvx install teamspeak-mcp
# Add to Claude Desktop config with CLI args
```
**Most Reliable (Docker):**
```bash
docker pull ghcr.io/marlburrow/teamspeak-mcp:latest
# Add to Claude Desktop config with env vars in args
```
**Most Flexible (Local):**
```bash
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
```bash
python install.py
```
### Connection test
```bash
python test_mcp.py
```
### With Docker
```bash
# 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:
```bash
# 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**
```bash
# 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:**
```json
{
"mcpServers": {
"teamspeak": {
"command": "uvx",
"args": ["teamspeak-mcp", "--host", "your-server.example.com", "--user", "mcp_user", "--password", "secure_password123"]
}
}
}
```
**For Docker installation:**
```json
{
"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
```bash
# Install development dependencies
pip install -r requirements.txt
# Run tests
python test_mcp.py
# Start MCP server
python -m teamspeak_mcp.server
```
### Docker build
```bash
# 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:**
```bash
# 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):**
```bash
# 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
```bash
# With Docker
docker logs container-name
# Without Docker
python -m teamspeak_mcp.server --verbose
```
## 📝 License
MIT