Codesandbox Mcp

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.
• sessionId (string, optional): Provide a specific session ID; if omitted a UUID is generated.
• permission (read|write): Session permission. Use read for safe, non-mutating access.
• env (Record, optional): Environment variables for the session.
• git (object, optional): Git identity/options for the session creation.
• provider (string): e.g. "github".
• username (string, optional)
• accessToken (string, optional)
• email (string)
• name (string, optional)

• resumeSession
• Description: Connect to an existing session by sandboxId + sessionId. If the session does not exist, it will be created using the optional parameters.
• Params:
• sandboxId (string): Target sandbox ID.
• sessionId (string): Session identifier to connect to.
• permission (read|write, optional): Used if creating the session.
• env (Record, optional): Used if creating the session.

• readFile
• Description: Read a file from the sandbox filesystem. The tool connects per call using sandboxId + sessionId.
• Params:
• sandboxId (string): Target sandbox ID.
• sessionId (string): Session identifier (created if missing as needed).
• permission (read|write, optional): Used if creating the session.
• env (Record, optional): Used if creating the session.
• path (string): Absolute path inside the sandbox filesystem.
• encoding (utf8|base64, optional): Encoding for the returned content (default utf8).

• readdir
• Description: List files and directories at a given path. The tool connects per call using sandboxId + sessionId.
• Params:
• sandboxId (string): Target sandbox ID.
• sessionId (string): Session identifier (created if missing as needed).
• permission (read|write, optional): Used if creating the session (defaults to read in read-only mode).
• env (Record, optional): Used if creating the session.
• path (string): Absolute path to list within the sandbox filesystem.

• writeFile
• Description: Write a file in the sandbox filesystem. The tool connects per call using sandboxId + sessionId.
• Params:
• sandboxId (string): Target sandbox ID.
• sessionId (string): Session identifier (created if missing as needed). Must allow write.
• permission (read|write, optional): Used if creating the session (typically write).
• env (Record, optional): Used if creating the session.
• path (string): Absolute path to the file.
• content (string): Content to write (encoded per encoding).
• encoding (utf8|base64, optional): Content encoding (default utf8).
• overwrite (boolean, optional): Overwrite existing file (default true).
• create (boolean, optional): Create the file if missing (default true).

• rename
• Description: Rename/move a file or directory. The tool connects per call using sandboxId + sessionId.
• Params:
• sandboxId (string): Target sandbox ID.
• sessionId (string): Session identifier (created if missing as needed). Must allow write.
• permission (read|write, optional): Used if creating the session (typically write).
• env (Record, optional): Used if creating the session.
• from (string): Source path.
• to (string): Destination path.
• overwrite (boolean, optional): Overwrite if destination exists (default true).

Notes:

• Filesystem operations connect a SandboxClient for the duration of the call and dispose it immediately; no state is retained.
• Outputs are returned as text blocks (JSON payloads serialized to string) for broad client compatibility.

Development

• Build: npm run build
• Dev (stdio): npm run dev (requires token env var)

Environment

• CODESANDBOX_API_TOKEN (preferred) or CSB_API_KEY: PAT with scopes for Sandbox Creation, Read/Edit, VM Manage, Preview Token Manage.

Limitations

• This server targets CodeSandbox sandboxes (VMs), not legacy projects.
• Session resume uses sandbox.connect({ id: sessionId }).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: techlibs
• Source: techlibs/codesandbox-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.