Minecraft Websocket API

Async Python client library for the Minecraft WebSocket API mod

Features

• Clean Async API - Modern async/await syntax with asyncio
• Event System - Subscribe to game events with decorators (@PlayerChatEvent, @PlayerJoinEvent, etc.)
• Type-safe - Full typing support with .pyi stubs for better IDE autocomplete
• Comprehensive - Player, Level, Block, Server, Entity, and Scoreboard management
• Lightweight - Minimal dependencies (just websockets)
• Easy to Use - Intuitive object-oriented interface

Installation

pip install mcwebapi

Quick Start

import asyncio
from mcwebapi import MinecraftAPI

async def main():
    async with MinecraftAPI() as api:
        # Get server info
        server = api.Server()
        info = await server.getInfo()
        print(f"Connected to {info['version']}")

        # Give items to player
        player = api.Player("Steve")
        await player.giveItem("minecraft:diamond", 64)
        await player.sendMessage("You received 64 diamonds!")

        # Set time to day
        level = api.Level("minecraft:overworld")
        await level.setDayTime(6000)

if __name__ == "__main__":
    asyncio.run(main())

Event System

Subscribe to Minecraft events using decorators:

from mcwebapi import MinecraftAPI
from mcwebapi.events import PlayerChatEvent, PlayerJoinEvent

@PlayerChatEvent
async def on_chat(event):
    print(f"{event.player_name}: {event.message}")

@PlayerJoinEvent
async def on_join(event):
    print(f"{event.player_name} joined!")

async def main():
    async with MinecraftAPI() as api:
        events = api.events()
        await events.start()
        try:
            while True:
                await asyncio.sleep(1) # Keep alive
        except KeyboardInterrupt:
            print("\nStopping...")

asyncio.run(main())

Available Events:

• @PlayerJoinEvent - Player joins server
• @PlayerQuitEvent - Player leaves server
• @PlayerChatEvent - Player sends chat message
• @PlayerDeathEvent - Player dies
• @BlockBreakEvent - Block broken
• @BlockPlaceEvent - Block placed
• @EntitySpawnEvent - Entity spawns
• @EntityDeathEvent - Entity dies

Documentation

📖 Full Documentation on Wiki

• Quick Start Guide - Get started quickly
• Player Operations - Health, inventory, effects, teleportation
• Block Operations - Place blocks, manage inventories
• Entity Management - Spawn and control entities
• Level Management - Time, weather, world settings
• Scoreboard - Objectives, teams, scores
• Server Management - Server info and administration
• Code Examples - Practical examples for common tasks

Server Setup

Requires the MinecraftWebsocketAPI mod on your Minecraft 1.21.1 server.

Basic Setup:

1. Install the NeoForge mod
2. Configure config/mcwebapi-server.toml with your settings (port, auth key)
3. Restart the server

Python Client:

api = MinecraftAPI(
    host="localhost",
    port=8765,
    auth_key="your-secret-key"
)

Requirements

• Python 3.8+
• websockets>=12.0
• Minecraft 1.21.1 server with MinecraftWebsocketAPI mod

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

Links

• Documentation: Wiki
• PyPI: pypi.org/project/mcwebapi
• Server Mod: MinecraftWebsocketAPI
• Issues: GitHub Issues