sbox -library

The s&box MCP server exposes a Model Context Protocol interface over WebSocket and stdio, enabling your AI assistant to send MCP tool calls that are translated into commands for the s&box editor. The server is implemented in .NET 9.0 and is intended to run locally, coordinating between the AI agent and the s&box editor. Once connected, you can issue natural-language or structured MCP tool requests to manage game objects and components in your s&box scene. Supported capabilities include creating and querying components, retrieving objects by name, and adjusting component properties, all mediated through the MCP tool layer and sent to the editor in real time.

To start, run the server using the build/run workflow described in the Quick Start. After the server is running, configure your MCP-enabled AI assistant (such as Cursor Editor or other MCP clients) to point at the server. The typical setup uses the in-editor MCP connection flow: open s&box, navigate to MCP → Connect to MCP Server, and connect to the running server. Once connected, you can issue commands like creating a ModelRenderer component, listing components on a game object, or updating Transform properties, and you will receive contextual responses and results back through the MCP channel.

Prerequisites

• .NET 9.0 SDK (or later) installed on your development machine
• s&box installed and up-to-date
• An MCP-compatible AI assistant (e.g., Cursor Editor, Claude Desktop, etc.)

Installation steps

1. Clone the repository

git clone https://github.com/suiramdev/sbox-mcp-server.git
cd sbox-mcp-server

2. Ensure prerequisites are installed

• Verify dotnet is available: dotnet --version
• Verify s&box is installed and can be opened

3. Build the server

dotnet restore
dotnet build Server/SandboxModelContextProtocol.Server.csproj -c Release

4. Run the server

dotnet run -p Server/SandboxModelContextProtocol.Server.csproj

5. Configure the AI assistant to connect to the MCP server (example path shown in the README)

• For Cursor Editor, add or update mcp.json with the server entry (see README for exact JSON example).

Notes

• The Quick Start advises using the build.ps1 script for Windows users:

./build.ps1 run

• The WebSocket server defaults to port 8080 as shown in Server/appsettings.json. You can adjust this as needed in the configuration.

Tips and common issues:

• Ensure the server is running with the correct working directory so the Server project outputs are accessible.
• If the MCP client cannot connect, verify the WebSocket URL and path in Server/appsettings.json and ensure firewall rules allow local connections.
• The available tools are grouped into Component Management and Game Object Management. Use them to manipulate components on game objects or query objects by name.
• The build script provides multiple shortcuts (build, run, publish, test). Use .\build.ps1 run to start in a convenient, repeatable way on Windows.
• If you modify the server code, re-build before testing with the AI assistant to ensure changes are reflected.

Environment variables you might encounter:

• None required for normal operation; the server config is typically provided via appsettings.json and the command-line invocation via the MCP config.