Skip to content
Observe a TeamSpeak3 Server and Manage clients, groups and channels
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


The ts3observer (teamspeak 3 observer) is a plugin-based tool to observe a Teamspeak 3 Server. It allows you to interact with clients, groups and channels. For example, move clients if they are idle, kick clients with unwanted nicknames or simply message a group if some client complaints about another.

For more information, examples and developer information, read the Wiki.


First you need to clone the tool:

git clone

After that, you need some requirements:

sudo apt-get install python python-yaml pip
pip install -r requirements.txt


After a successful installation, you need to configure the ts3observer with the main configuration file unter conf/.

You should copy the ts3observer.yml.skel to ts3observer.yml and modify the new file to match your settings.


You can run the ts3observer with python run.

To view all available commands, type python ts3observer --help


Since the ts3observer is plugin based, every tasks that manages clients, channels or groups should be delegated to plugins. One plugin should cover one topic of tasks.

There are already some Plugins available.

You can add plugins by copying the in the plugins/ folder while the ts3observer is not running.

If you now start the ts3observer, it will "load" all plugins it can find in the plugin folder.

If it finds any new plugins (plugins without a config file), it will create a default config in the conf/ folder, log the new plugin as '[NEW]' and stops after all plugins are loaded and initialized to allow you to configure the new created config files.

Important notes

It is recommended to run the ts3observer locally on the server where your teamspeak server in running. You can run it remotely, but then you have to write the IP address of the remote server to teamspeak's query_ip_whitelist.txt.

To avoid all this mess, simply make sure that ts3observer is running beside the teamspeak server and that a local IP adress like localhost or is written in teamspeak's query_ip_whitelist.txt. Should be by default.

You can’t perform that action at this time.