teamspeak3-mcp
by fl0w1nd
README.md
<div align="center">
# TeamSpeak 3 MCP Server
**Let AI models manage your TeamSpeak 3 server through the Model Context Protocol.**
[](https://www.npmjs.com/package/teamspeak3-mcp)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](https://zread.ai/fl0w1nd/teamspeak3-mcp)
[](https://lobehub.com/mcp/fl0w1nd-teamspeak3-mcp)
[English](README.md) · [中文](README.zh-CN.md)
</div>
---
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes TeamSpeak 3 ServerQuery operations as AI-callable tools. Connect Claude, Cursor, or any MCP-compatible client to manage your TeamSpeak server with natural language.
## Features
- **35 purpose-built tools** covering server management, channels, clients, groups, permissions, moderation, and more
- **Lazy connection** — connects to TeamSpeak only when the first tool is invoked
- **Exponential backoff retry** — automatic reconnection with up to 3 attempts
- **Graceful shutdown** — cleans up the ServerQuery session on process exit
- **Centralized error handling** — every tool returns structured MCP error responses
- **Zero-config transport** — runs over `stdio`, works out-of-the-box with any MCP client
## Requirements
- **Node.js** >= 18
- A TeamSpeak 3 server with **ServerQuery** access (port `10011` by default)
## Getting Started
Add the following to your MCP client configuration. This works with most clients:
```json
{
"mcpServers": {
"teamspeak": {
"command": "npx",
"args": ["teamspeak3-mcp"],
"env": {
"TEAMSPEAK_HOST": "your-server.com",
"TEAMSPEAK_PASSWORD": "your-password"
}
}
}
}
```
No installation needed — `npx` downloads and runs the package automatically.
### Claude Desktop
Add to your Claude Desktop config file (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"teamspeak": {
"command": "npx",
"args": ["teamspeak3-mcp"],
"env": {
"TEAMSPEAK_HOST": "your-server.com",
"TEAMSPEAK_PASSWORD": "your-password"
}
}
}
}
```
### Cursor
Add to your Cursor MCP settings (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"teamspeak": {
"command": "npx",
"args": ["teamspeak3-mcp"],
"env": {
"TEAMSPEAK_HOST": "your-server.com",
"TEAMSPEAK_PASSWORD": "your-password"
}
}
}
}
```
## Configuration
Configuration is resolved from **CLI arguments** first, then **environment variables**, with sensible defaults as fallback.
| Parameter | CLI Flag | Env Variable | Default |
|---|---|---|---|
| Host | `--host` | `TEAMSPEAK_HOST` | `localhost` |
| Query Port | `--port` | `TEAMSPEAK_PORT` | `10011` |
| Username | `--user` | `TEAMSPEAK_USER` | `serveradmin` |
| Password | `--password` | `TEAMSPEAK_PASSWORD` | *(required)* |
| Virtual Server ID | `--server-id` | `TEAMSPEAK_SERVER_ID` | `1` |
| Enabled Tools | `--tools` | `TEAMSPEAK_TOOLS` | *(all)* |
> **Note:** `TEAMSPEAK_PASSWORD` refers to the **ServerQuery login password**, not the TeamSpeak server connection password. You can find it in the server console output on first start, or create one via **Tools → ServerQuery Login** in the TeamSpeak client.
### Selective Tool Loading
By default all 35 tools are registered. Use `TEAMSPEAK_TOOLS` (or `--tools`) with a comma-separated list of module names to load only what you need — useful for reducing the tool list exposed to the AI model:
```json
{
"mcpServers": {
"teamspeak": {
"command": "npx",
"args": ["teamspeak3-mcp"],
"env": {
"TEAMSPEAK_HOST": "your-server.com",
"TEAMSPEAK_PASSWORD": "your-password",
"TEAMSPEAK_TOOLS": "server,channel,client"
}
}
}
}
```
Available modules: `server`, `channel`, `client`, `sgroup`, `cgroup`, `permission`, `messaging`, `moderation`, `token`, `file`
## Tools Reference
### Server (`server_*`)
| Tool | Description |
|---|---|
| `server_info` | Get server details (scope: `overview` or `connection` statistics) |
| `server_list` | List resources (resource: `clients`, `channels`, `server_groups`, `channel_groups`) |
| `server_search` | Search for clients or channels by pattern |
| `server_log` | View recent virtual server or instance log entries |
| `server_diagnose` | Run a diagnostic check on the current connection's permissions |
### Channel (`channel_*`)
| Tool | Description |
|---|---|
| `channel_create` | Create a new channel (permanent or temporary) |
| `channel_delete` | Delete a channel (with optional force flag) |
| `channel_update` | Update channel properties (name, password, codec, talk power, etc.) |
| `channel_info` | Get detailed channel information |
| `channel_perm` | Add, remove, or list permissions on a channel |
### Client (`client_*`)
| Tool | Description |
|---|---|
| `client_info` | Get detailed info: platform, version, country, IP, idle time, etc. |
| `client_move` | Move a client to another channel |
| `client_kick` | Kick a client from the server or channel |
| `client_ban` | Ban a client (timed or permanent) |
| `client_perm` | Manage server group membership and individual permissions |
| `client_db_list` | List historical clients from the server database (includes offline clients) |
| `client_poke` | Send a poke alert notification to a client |
### Server Group (`sgroup_*`)
| Tool | Description |
|---|---|
| `sgroup_create` | Create a new server group |
| `sgroup_delete` | Delete a server group |
| `sgroup_perm` | Add, remove, or list permissions on a server group |
| `sgroup_clients` | List all clients assigned to a server group |
### Channel Group (`cgroup_*`)
| Tool | Description |
|---|---|
| `cgroup_create` | Create a new channel group |
| `cgroup_perm` | Add, remove, or list permissions on a channel group |
| `cgroup_assign` | Assign a client to a channel group in a specific channel |
### Permission (`perm_*`)
| Tool | Description |
|---|---|
| `perm_list` | List all available permission definitions (name, ID, description) |
| `perm_find` | Find all assignments of a permission across the server |
| `perm_overview` | Get effective permission overview for a client in a channel |
### Messaging (`msg_*`)
| Tool | Description |
|---|---|
| `msg_send` | Send a text message (mode: `channel` or `private`) |
### Moderation (`ban_*` / `complaint_*`)
| Tool | Description |
|---|---|
| `ban_list` | List all active ban rules |
| `ban_manage` | Create, delete, or clear ban rules by IP/name/UID |
| `complaint_list` | List complaints (optionally filtered by target client) |
### Tokens (`token_*`)
| Tool | Description |
|---|---|
| `token_list` | List all available privilege keys/tokens |
| `token_create` | Create a server group or channel group token |
### Files (`file_*`)
| Tool | Description |
|---|---|
| `file_list` | List files in a channel's file repository |
| `file_info` | Get detailed info about a specific file |
## Development
```bash
git clone https://github.com/fl0w1nd/teamspeak3-mcp.git
cd teamspeak3-mcp
pnpm install
pnpm build # Build the project
pnpm dev # Watch mode (auto-rebuild on changes)
pnpm inspect # Debug with MCP Inspector (web UI)
```
### MCP Inspector
The project includes a pre-configured script for the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), a web-based debugging tool:
```bash
pnpm inspect
```
This launches a local web UI where you can browse available tools, invoke them interactively, and inspect request/response payloads — useful for development and troubleshooting.
### Project Structure
```
src/
├── index.ts # Entry point, stdio transport, graceful shutdown
├── config.ts # CLI + env configuration parsing
├── connection.ts # TeamSpeak connection with retry & lazy init
├── server.ts # MCP server setup & tool registration
├── utils/
│ └── tool-handler.ts # Error handling & response utilities
└── tools/
├── server.ts # Server info, resource listing, search, logs, diagnostics
├── channel.ts # Channel CRUD & permissions
├── client.ts # Client management, permissions & poke
├── server-group.ts # Server group CRUD, permissions & members
├── channel-group.ts # Channel group CRUD, permissions & assignment
├── permission.ts # Global permission queries & overview
├── messaging.ts # Channel & private messaging
├── moderation.ts # Bans & complaints
├── token.ts # Privilege token management
└── file.ts # Channel file browser
```
## License
[MIT](LICENSE)
TDQS
B3.2/5.0
Scored across 35 tools
Disambiguation4/5
Most tools have clearly distinct purposes, but the perm_* family (perm_overview, perm_list, perm_find, channel_perm, client_perm, sgroup_perm, cgroup_perm) has overlapping 'manage permissions' functions that could confuse without careful reading. Similarly, ban_* tools (ban_list, ban_manage, client_ban) have some overlap. Descriptions help distinguish them, but boundaries aren't always crisp.
Naming Consistency4/5
Tool names mostly use a consistent verb_noun or noun_verb pattern (e.g., channel_create, client_kick, sgroup_perm), but there are minor deviations like server_list (noun_verb) and sgroup_create (abbreviated noun). The abbreviations (sgroup, cgroup, perm) are consistent within categories, making the naming predictable overall.
Tool Count3/5
With 35 tools, the count is heavy for a TeamSpeak server management MCP. While many are distinct operations, the number could overwhelm an agent, and some tools (e.g., perm_overview vs perm_list) might be consolidated. The scope is broad, but the count feels borderline excessive.
Completeness4/5
The tool set covers most CRUD operations for channels, clients, server groups, channel groups, permissions, bans, messages, files, tokens, and complaints. However, some gaps exist: no tools for banning by IP/range, no detailed server group info beyond permissions, and no file upload/download operations. These are minor but noticeable for a complete management surface.
Maintenance
ActivityInactive
ResponsivenessNo issues