mcbe-ws-sdk

Generic WebSocket gateway SDK for Minecraft Bedrock Edition.

It owns the WS transport, packet protocol, and byte-safe command chunking (461-byte empirically measured default ceiling; deployments may lower it). Your host injects behaviour through typed ConnectionHook and ResponseSink interfaces, with optional typed session/approval control callbacks, and drives the stack with McbeServerFacade.

There is no message broker and no LLM worker inside the SDK — those stay in the host application.

Minecraft client  ←── /wsserver IP:port ──→  Your Python host (this SDK)

In-game addon capability bridge

Use the companion TypeScript addon when your host needs structured information or Script API actions from inside the world—not just player chat. A capability call follows one correlated, chunk-safe round trip:

Python host
  → AddonBridgeService request(capability, payload)
  → scriptevent mcbews:bridge_req
  → addon capability handler in the Bedrock world
  → MCBEWS_BRIDGE simulated-player chat chunks
  → WebSocket PlayerMessage stream
  → AddonBridgeSession reassembles by request_id and resolves the request
  → your host renders the result (tellraw or mcbews:text_resp)

• Bidirectional by design. Python calls addon capabilities; the addon can also send UI-originated player messages back through the same bridge. Python can send framed text responses to the addon UI with mcbews:text_resp.
• Safe on the actual transport. Requests and responses carry a request_id; large payloads are chunked and reassembled rather than relying on a direct addon-to-WebSocket connection.
• Clear ownership. The addon owns its capability registry; the Python host owns authentication and authorization. The bridge itself is not a security boundary.

Start with the runnable addon-server example and the bridge protocol. To load the companion addon, the target world must enable Experiments → Beta APIs; otherwise its scripts do not load and capability calls time out.

Install

pip install mcbe-ws-sdk

Editable install for development:

pip install -e ".[dev,docs]"

Requires Python 3.11+.

30-second taste

import asyncio
from mcbe_ws_sdk import McbeServerFacade, NoOpHook


class MyHook(NoOpHook):
    async def on_connected(self, state):
        print("connected:", state.id)

    async def on_player_message(self, state, event, parsed=None):
        print(f"{event.sender}: {event.message}")


async def main() -> None:
    facade = McbeServerFacade(hook=MyHook())
    print(f"ws://{facade.settings.websocket.host}:{facade.settings.websocket.port}")
    await facade.run_lifetime()


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

Then in Minecraft: /wsserver <this-machine-ip>:8080

For a reply-with-tellraw host, run the ready-made example:

python examples/basic-server/server.py

Documentation

Full beginner tutorial, architecture, protocol, and API reference live on the docs site (English + 中文):

Examples

Companion TypeScript addon: addon/. Worlds that load it must enable Experiments → Beta APIs (see addon README).

Development

pip install -e ".[dev,docs]"
ruff check --no-cache src tests examples
mypy --no-incremental src
pytest -p no:cacheprovider -q
python tools/format.py          # ruff format+fix (Python); prettier (Addon if Node)
python tools/format.py --check  # CI-style check

License

MIT