📡 SpyWebSocket
SpyWebSocket is a lightweight Paper plugin that exposes a secure WebSocket API for remotely interacting with a Minecraft server.
It allows external programs (such as Python scripts, bots, or automation tools) to authenticate, execute console commands, and retrieve live player data in real time using structured JSON messages.
This plugin is designed for local or trusted network usage and focuses on simplicity, flexibility, and thread safety.
✨ Features
🔐 Authentication system Clients must authenticate before accessing any functionality.
📡 Built-in WebSocket server No proxies or external services required.
🧵 Thread-safe command execution All commands are dispatched on the Minecraft main thread.
📍 Live player coordinates API Retrieve world and position data for all online players.
⚙️ Fully configurable Host, port, username, and password are configurable via config.yml.
🧩 JSON-based protocol Simple, human-readable messages for easy integration.
⚙️ Configuration (config.yml) websocket: host: 127.0.0.1 port: 8765 username: admin password: strongpassword
⚠️ Security warning: Keep the server bound to 127.0.0.1 or protect it with a firewall. This plugin allows remote console command execution.
🔐 Authentication
Clients must authenticate first before using any other action.
➤ Request
{
"type": "auth",
"username": "admin",
"password": "strongpassword"
}
➤ Success Response
{
"type": "auth_ok"
}
➤ Failure Response
{
"type": "auth_fail"
}
🧾 Execute Console Commands
Executes a command as the server console.
➤ Request
{
"type": "command",
"command": "say Hello from WebSocket"
}
Commands are executed safely on the main server thread.
📍 Get Online Player Coordinates
Returns position and world data for all online players.
➤ Request
{
"type": "get_players"
}
➤ Response
{
"type": "players",
"players": {
"Notch": {
"x": 123.45,
"y": 64.0,
"z": -98.32,
"world": "world"
},
"Steve": {
"x": -20.0,
"y": 70.0,
"z": 45.1,
"world": "world_nether"
}
}
}
❌ Error Responses
If a request is invalid or unauthorized, the server responds with:
{
"type": "error",
"reason": "not_authenticated"
}
Common error reasons:
invalid_json
missing_type
unknown_type
not_authenticated
🧠 Use Cases
Python-controlled Minecraft automation
Admin dashboards or monitoring tools
Twitch / chat integrations
Live overlays or external UIs
Custom moderation tools
🛡️ Security Notes
Only authenticated clients can issue commands or access data
Intended for trusted environments
Not recommended for public-facing servers without additional protection
📌 Compatibility
Platform: Paper
Minecraft version: 1.21+
Java version: 21
Dependency handling: Shaded (Shadow JAR)
⚠️ Disclaimer
This plugin enables remote execution of server console commands. Use responsibly and only on servers you trust.
