sbox-mcp-server by TheNotoriousV1 - MCP Server

s&box MCP Server

A Model Context Protocol (MCP) server for s&box game development, enabling AI assistants to interact with the s&box editor and game objects in real-time.

Features

Real-time Editor Integration: Connect AI assistants directly to the s&box editor
Game Object Manipulation: Create, modify, and manage game objects programmatically
Scene Management: Load, save, and manipulate scenes
Component System: Add, remove, and configure components on game objects
Physics Integration: Control rigidbodies, colliders, and physics properties
WebSocket Communication: Real-time bidirectional communication

Installation

Prerequisites

.NET 7.0 or later
s&box editor
Node.js (for the adapter library)

Setup

Clone the repository:

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

Build the server:
```
dotnet build
```
Run the server:
```
dotnet run
```

Configure Cursor: Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "sbox": {
      "url": "http://localhost:8080",
      "type": "http"
    }
  }
}

Usage

Basic Commands

Create Game Object: mcp_sbox_create_game_object
Set Position: mcp_sbox_set_game_object_world_position
Add Component: mcp_sbox_add_game_object_component
Load Scene: mcp_sbox_load_editor_scene_from_path

Example Workflow

Start the MCP server
Open s&box editor
Connect your AI assistant (Cursor)
Use MCP commands to manipulate the scene

API Reference

Game Object Operations

Function	Description
`mcp_sbox_create_game_object`	Create a new game object
`mcp_sbox_destroy_game_object`	Delete a game object
`mcp_sbox_get_game_object_by_id`	Get game object by ID
`mcp_sbox_get_game_object_by_name`	Get game object by name
`mcp_sbox_set_game_object_name`	Rename a game object

Transform Operations

Function	Description
`mcp_sbox_set_game_object_world_position`	Set world position
`mcp_sbox_set_game_object_local_position`	Set local position
`mcp_sbox_set_game_object_world_rotation`	Set world rotation
`mcp_sbox_set_game_object_local_rotation`	Set local rotation
`mcp_sbox_set_game_object_world_scale`	Set world scale
`mcp_sbox_set_game_object_local_scale`	Set local scale

Component Operations

Function	Description
`mcp_sbox_add_game_object_component`	Add component to game object
`mcp_sbox_remove_game_object_component`	Remove component from game object
`mcp_sbox_get_game_object_component`	Get specific component
`mcp_sbox_get_game_object_components`	Get all components
`mcp_sbox_set_game_object_component_property`	Set component property

Scene Operations

Function	Description
`mcp_sbox_load_editor_scene_from_path`	Load scene from file path
`mcp_sbox_get_active_editor_scene`	Get current active scene
`mcp_sbox_save_active_editor_session`	Save current editor session
`mcp_sbox_save_all_editor_sessions`	Save all editor sessions

Configuration

Server Configuration

The server runs on http://localhost:8080 by default. You can modify the port in Program.cs:

builder.WebHost.UseUrls("http://0.0.0.0:8080");

Security Considerations

The server runs on localhost by default
No authentication is implemented (suitable for local development)
Consider implementing authentication for production use

Troubleshooting

Common Issues

Server won't start: Check if port 8080 is available
Connection refused: Ensure s&box editor is running
Commands not working: Verify the adapter library is properly installed

Debug Mode

Enable debug logging by setting the log level in appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see LICENSE file for details

Support

GitHub Issues: Report bugs and request features
Discord: Join the s&box community Discord
Documentation: s&box MCP Documentation

Changelog

v1.0.0

Initial release
Basic game object manipulation
Scene management
Component system integration
WebSocket communication