TeamSpeak 3 MCP Server

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

English · 中文

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.

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_*)

Channel (channel_*)

Client (client_*)

Server Group (sgroup_*)

Channel Group (cgroup_*)

Permission (perm_*)

Messaging (msg_*)

Moderation (ban_* / complaint_*)

Tokens (token_*)

Files (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