Skip to content

addavriance/MinecraftWebsocketAPI

Repository files navigation

mcwebapi

Minecraft WebSocket API

Control Minecraft in real-time from any programming language

PyPI NeoForge License

Python Client PyPI Wiki

FeaturesInstallationQuick StartAPI ModulesDocs


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:

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

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

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

Spawn, remove, teleport, and customize entities

Objectives, teams, scores, display slots

Server info, monitoring, player management, commands

📖 View Full API Documentation →


Documentation


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

About

Mod for interacting with the game via Websockets

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages