<div align="center">

TeamSpeak 3 MCP Server

Let AI models manage your TeamSpeak 3 server through the Model Context Protocol.

English · 中文

</div>

---

A Model Context Protocol (MCP) 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:

{
  "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):

{
  "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):

{
  "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:

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

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, a web-based debugging tool:

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