Minecraft WebSocket API

Control Minecraft in real-time from any programming language

Features • Installation • Quick Start • API Modules • Docs

What is this?

A client/server-side NeoForge mod that exposes Minecraft's functionality through a WebSocket API, enabling real-time control from external applications in any programming language.

# It's THIS simple:
import asyncio
from mcwebapi import MinecraftAPI

async def main():
    async with MinecraftAPI() as api:
        player = api.Player("Steve")
        await player.teleport(0, 100, 0)

        level = api.Level("minecraft:overworld")
        await level.setDayTime(6000)

        block = api.Block("minecraft:overworld")
        await block.setBlock(10, 64, 10, "minecraft:diamond_block")

asyncio.run(main())

Perfect for: Automation • Education • Custom Game Mechanics • Server Monitoring • Testing • Fun!

---

Features

Real-time Communication WebSocket-based for instant responses Thread-safe concurrent operations Non-blocking implementation <1% overhead on server tick time	Secure & Flexible Token authentication Optional SSL/TLS encryption CORS support Configurable timeouts & origins
Comprehensive API Player operations (health, inventory, teleport) World manipulation (blocks, time, weather) Block entities (chests, furnaces) Full NBT support	Python Client PyPI package (pip install mcwebapi) Async/await native asyncio support Type hints for IDE support Context managers for clean code

---

Installation

Server (Minecraft Mod)

1. Download the latest JAR from releases
2. Place in your server's mods/ folder
3. Start the server to generate config OR join signleplayer world
4. Edit config/mcwebapi-server.toml:

[websocket]
    port = 8765
    authKey = "your-secret-key-here"  # ⚠️ CHANGE THIS!
    enableSSL = false
    host = "0.0.0.0"

Client (Python)

pip install mcwebapi

---

Quick Start

Basic Example

import asyncio
from mcwebapi import MinecraftAPI

async def main():
    # Connect to your server
    async with MinecraftAPI(
        host="localhost",
        port=8765,
        auth_key="your-secret-key-here"
    ) as api:
        # Control players
        player = api.Player("Steve")
        await player.setHealth(20.0)
        await player.teleport(0, 100, 0)
        await player.sendMessage("Hello from Python!")

        # Manipulate world
        level = api.Level("minecraft:overworld")
        await level.setDayTime(6000)  # Noon
        await level.setWeather(True, False)  # Rain, no thunder

        # Interact with blocks
        block = api.Block("minecraft:overworld")
        await block.setBlock(10, 64, 10, "minecraft:diamond_block")

asyncio.run(main())

Concurrent Operations

import asyncio
from mcwebapi import MinecraftAPI

async def main():
    async with MinecraftAPI(auth_key="your-key") as api:
        # Get multiple values concurrently
        player1 = api.Player("Steve")
        player2 = api.Player("Alex")

        health1, health2 = await asyncio.gather(
            player1.getHealth(),
            player2.getHealth()
        )

        print(f"Steve: {health1}, Alex: {health2}")

asyncio.run(main())

---

API Modules

The Python client provides comprehensive access to all Minecraft server functionality:

🎮 Player Operations

Health, inventory, teleportation, effects, experience, game mode

🌍 Level Management

Time, weather, blocks, world border, spawn point, chunks

🧱 Block Operations

Place/break blocks, manage container inventories (chests, furnaces)

👾 Entity Management

Spawn, remove, teleport, and customize entities

🏆 Scoreboard

Objectives, teams, scores, display slots

⚙️ Server Management

Server info, monitoring, player management, commands

📖 View Full API Documentation →

---

Documentation

• Python Client Documentation - Complete API reference with examples
• Python Client GitHub - Source code and issues
• PyPI Package - Installation and releases

---

Security

Important Security Notes:

1. Change the default auth key immediately in config
2. Use SSL/TLS in production (set enableSSL = true)
3. Bind to localhost if not exposing externally (host = "127.0.0.1")
4. Firewall rules to restrict port access
5. Monitor logs for unauthorized attempts

---

Building from Source

git clone https://github.com/addavriance/MinecraftWebsocketAPI.git
cd MinecraftWebsocketAPI
./gradlew build

Output: build/libs/mcwebapi-1.3.0.jar

---

Troubleshooting

Port already in use

Change `port` in config or stop the conflicting service.

Authentication fails

Verify that `authKey` matches between server config and client code.

Stale data / caching issues

• Player cache TTL: 30 seconds
• World cache TTL: 60 seconds
• Caches auto-clear on logout/dimension change

Performance issues

• Reduce concurrent connections
• Monitor server TPS
• Check network latency

---

Contributing

Contributions are welcome! Please feel free to:

• Report bugs via Issues
• Suggest features
• Submit pull requests
• Improve documentation