sbox

This MCP server provides a bridge between AI assistants implementing the Model Context Protocol and the s&box editor via real-time WebSocket communication. When the server is running inside Docker, it exposes a WebSocket endpoint on port 8080 that your AI assistant can connect to and issue MCP tool calls. The server relies on the accompanying sbox adapter library to translate MCP commands into actions within the s&box editor, enabling you to manipulate game objects, components, and properties through natural language or scripted prompts. Typical usage involves connecting an AI assistant (like Cursor or Claude Desktop) to the MCP server and then issuing requests such as creating components, querying objects, or modifying properties. The flow is: AI assistant sends MCP calls → MCP server translates to WebSocket commands for the sbox adapter → adapter executes in the editor and returns results to the AI assistant via MCP server.

Example capabilities you can leverage include:

• Creating or modifying components on game objects (e.g., add a ModelRenderer to a Cube)
• Querying scene objects by name or type (e.g., find all objects named 'Player')
• Adjusting entity transforms or component properties (e.g., set Transform.Scale to 2,2,2)
• Removing components or querying attached components on objects

To use, ensure the MCP server is running in Docker as shown in the Quick Start, then connect your AI assistant to the server’s WebSocket endpoint and begin issuing MCP tool calls that the adapter library can execute in s&box.

Prerequisites:

• Docker (recommended) or .NET SDK if you prefer manual installation
• s&box installed on your machine
• An AI assistant that supports MCP (e.g., Cursor, Claude Desktop)

Installation steps (Docker):

1. Install Docker on your system and ensure it is running.
2. Pull and run the MCP server container in detached mode:

# Run the MCP server container in detached mode and expose port 8080
docker run -d -p 8080:8080 --name sbox-mcp-server ghcr.io/suiramdev/sbox-mcp-server:latest

3. Verify the container is running:

docker ps -a | grep sbox-mcp-server

4. Connect your AI assistant to the MCP server’s WebSocket endpoint (ws://<host>:8080).

Manual (non-Docker) installation (optional):

• If you prefer building from source with .NET SDK, follow the repository’s standard .NET build/install steps, then run the server locally and expose the appropriate port.

Notes:

• The Docker method is the recommended approach as per the Quick Start in the README.
• Ensure port 8080 is accessible from your AI assistant and any firewalls allow traffic.

Tips and notes:

• The server works with the s&box Adapter Library to communicate with the editor; ensure you have installed and configured the adapter in your s&box project.
• The MCP server relies on the adapter to translate MCP tool calls into editor actions. If you encounter issues, verify that the adapter library is properly installed and connected.
• Use the latest container image tag (latest) or pin to a stable version for production.
• If you encounter connection issues, check that the server container is running and that the host can reach port 8080. Review logs with: docker logs sbox-mcp-server