TeamSpeak 3 MCP Server

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

npm version License: MIT TypeScript Node.js MCP SDK zread MCP Badge

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

teamspeak3-mcp

TeamSpeak 3 MCP Server

Features

Requirements

Getting Started

Claude Desktop

Cursor

Configuration

Selective Tool Loading

Tools Reference

Server (`server_*`)

Channel (`channel_*`)

Client (`client_*`)

Server Group (`sgroup_*`)

Channel Group (`cgroup_*`)

Permission (`perm_*`)

Messaging (`msg_*`)

Moderation (`ban_` / `complaint_`)

Tokens (`token_*`)

Files (`file_*`)

Development

MCP Inspector

Project Structure

License

Latest Blog Posts

MCP directory API

TeamSpeak 3 MCP Server

Features

Requirements

Getting Started

Claude Desktop

Cursor

Configuration

Selective Tool Loading

Tools Reference

Server (server_*)

Channel (channel_*)

Client (client_*)

Server Group (sgroup_*)

Channel Group (cgroup_*)

Permission (perm_*)

Messaging (msg_*)

Moderation (ban_* / complaint_*)

Tokens (token_*)

Files (file_*)

Development

MCP Inspector

Project Structure

License

Latest Blog Posts

MCP directory API

Server (`server_*`)

Channel (`channel_*`)

Client (`client_*`)

Server Group (`sgroup_*`)

Channel Group (`cgroup_*`)

Permission (`perm_*`)

Messaging (`msg_*`)

Moderation (`ban_` / `complaint_`)

Tokens (`token_*`)

Files (`file_*`)