CodeSandbox MCP Server

A Model Context Protocol (MCP) server that exposes CodeSandbox SDK operations as tools for AI agents.

• Runtime: Node.js 18+
• Auth: CODESANDBOX_API_TOKEN (or CSB_API_KEY)
• SDK: Official @codesandbox/sdk

Install / Run

Use via npx in your MCP client config.

Example (Cursor/Claude Desktop mcp.json snippet):

{
  "mcpServers": {
    "codesandbox": {
      "command": "npx",
      "args": [
        "-y",
        "@techlibs/codesandbox-mcp@latest",
        "--read-only"
      ],
      "env": {
        "CODESANDBOX_API_TOKEN": ""
      }
    }
  }
}

CLI binary name: mcp-server-codesandbox

You can also run directly:

npx -y @techlibs/codesandbox-mcp@latest --help

Flags:

• --read-only: disallow mutating tools (write/rename) and default sessions to read permission
• --vm-tier : default VM tier when creating/resuming
• --hibernation-timeout : default inactivity hibernation timeout
• --keep-alive: keep sessions active while connected
• --log-level

Tools (Stateless)

All tools are stateless: no server-managed session registry. Each call performs the SDK operation directly using only the provided arguments.

• createSandbox

  • Description: Create a sandbox (optionally from template id) and optionally start with custom VM settings.
  • Params:
    • privacy (public|private): Privacy of the sandbox.
    • title (string): Optional title.
    • description (string): Optional description.
    • tags (string[]): Up to 10 tags.
    • path (string): Destination folder path inside your workspace.
    • id (string): Template sandbox ID to fork from.
    • ipcountry (string): ISO 3166-1 alpha-2 country hint for VM scheduling.
    • vmTier (string): VM tier (e.g. Pico, Nano, …). Overrides server default.
    • hibernationTimeoutSeconds (number): Inactivity timeout before VM hibernates.
    • automaticWakeupConfig.http (boolean): Auto-wake on HTTP.
    • automaticWakeupConfig.websocket (boolean): Auto-wake on WebSocket.

• resumeSandbox

  • Description: Resume (or start) a sandbox VM.
  • Params:
    • sandboxId (string): Target sandbox ID.

• hibernateSandbox

  • Description: Hibernate a sandbox VM (saves and sleeps the VM).
  • Params:
    • sandboxId (string): Target sandbox ID.

• getSandboxInfo

  • Description: Get sandbox metadata without starting the VM.
  • Params:
    • sandboxId (string): Sandbox ID to fetch.

• updateSandbox

  • Description: Update VM settings for a running sandbox.
  • Params:
    • sandboxId (string): Target sandbox ID.
    • vmTier (string): Change VM tier (Pico|Nano|Micro|Small|Medium|Large|XLarge).
    • hibernationTimeoutSeconds (number): Update inactivity hibernation timeout.

• createSession

  • Description: Create a session for a sandbox (no state is stored server-side).
  • Params:
    • sandboxId (string): Target sandbox ID.