ChatGPT Box MCP

A private MCP server that lets ChatGPT create and operate your own Box by ASCII Linux environments.

The control direction is deliberately one-way:

ChatGPT
  → private Developer Mode MCP app
  → OpenAI Secure MCP Tunnel
  → this local MCP server
  → Box Public API
  → your Box Linux environments

ChatGPT remains the conversational interface and tool orchestrator. This project does not automate the ChatGPT website, extract ChatGPT responses, expose a ChatGPT account as an API, or call Box's built-in Codex/Claude prompt runner.

What it can do

The server exposes explicit, accurately annotated MCP tools:

Area	Tools
Discovery	`box_list`, `box_get`, `box_list_events`
Lifecycle	`box_create`, `box_stop`, `box_resume`, `box_fork`
Work	`box_execute_command`, `box_read_file`, `box_write_file`
Long-running work	`box_job_start`, `box_job_status`, `box_job_logs`, `box_job_cancel`
Visual inspection	`box_open_desktop`

Short commands wait for at most 60 seconds, matching the Box command API. Background jobs run independently inside the Box and persist their pid, status, and logs under .chatgpt-box-mcp/jobs/ in the Box work directory.

Safety model

BOX_API_KEY is read only from the MCP server's environment. It is never a tool argument or tool result.
Tool descriptions and MCP annotations state which actions write, may destroy data, or affect external systems.
File tools reject absolute paths and .. traversal segments.
Long-job scripts are base64 encoded before being installed in the Box, so their contents are not interpolated into the launcher shell.
A forced stop is marked destructive because it can lose changes since the last successful snapshot.
Desktop URLs are secret-bearing. The tool tells ChatGPT not to log, persist, or share them.
HTTP mode binds to loopback by default. Binding to a non-loopback address requires MCP_HTTP_TOKEN.

The server deliberately does not expose Box account secret-management or API-key-management endpoints.

Requirements

Node.js 22 or newer.
A Box by ASCII account and API key. Create one in the Box dashboard or with box api-key create.
For private ChatGPT use: access to ChatGPT Developer Mode and an OpenAI Secure MCP Tunnel.

Developer Mode and tunnel permissions are separate. Availability depends on your ChatGPT workspace/plan and OpenAI Platform organization permissions.

Install

npm.cmd install
npm.cmd run build
Copy-Item .env.example .env

Edit .env and set:

BOX_API_KEY=box_your_secret_here

Do not commit .env.

Run locally over stdio:

npm.cmd run start:env

The process waits for an MCP client on stdin/stdout. Log messages go to stderr so they do not corrupt the MCP stream.

Connect through OpenAI Secure MCP Tunnel

Create a tunnel in OpenAI Platform tunnel settings and associate it with the ChatGPT workspace that will use it.
Download the latest tunnel-client.
Use an absolute path for the MCP command. On Windows, for example:

$env:CONTROL_PLANE_API_KEY = "sk-your-runtime-key"

tunnel-client init `
  --sample sample_mcp_stdio_local `
  --profile chatgpt-box `
  --tunnel-id tunnel_replace_me `
  --mcp-command 'node --env-file=D:\Chat-box-mcp\.env D:\Chat-box-mcp\dist\src\index.js'

tunnel-client doctor --profile chatgpt-box --explain
tunnel-client run --profile chatgpt-box

Keep tunnel-client run healthy while using the app.

Open ChatGPT Plugins, create a developer-mode app, choose Tunnel, and select the tunnel.
Scan the tools and name the private app, for example ChatGPT Box MCP.

You can then ask:

@ChatGPT Box MCP list my running boxes.

@ChatGPT Box MCP create a one-hour small box, clone this repository,
run the tests, fix the failures, and show me the diff. Use a background
job if the work will take more than a minute.

ChatGPT should explain and confirm consequential tool calls according to the tool annotations and the current product policy.

Local HTTP mode and MCP Inspector

HTTP mode is useful for MCP Inspector and local diagnostics.

Set these values in .env:

MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=3000

Then run:

npm.cmd run start:env

Endpoints:

MCP: http://127.0.0.1:3000/mcp
Health: http://127.0.0.1:3000/healthz

If you intentionally bind beyond loopback, also set a strong MCP_HTTP_TOKEN and send it as Authorization: Bearer .... A public plugin needs additional authentication, deployment, and review work; this repository is designed for a private, manually configured Developer Mode app.

Development

npm.cmd run check
npm.cmd test

The tests cover Box request construction, structured API errors, credential isolation, long-job launcher safety, job status parsing, MCP initialization, tool discovery, and the missing-credential error path.

Operational notes

Box creation, resume, and fork operations can start billable machine time.
box_stop snapshots before stopping unless force=true is explicitly requested.
Cancelling a background job sends SIGTERM to its process group. It cannot roll back files or external side effects already produced.
Box API command output may itself be truncated by Box; large MCP results are also capped to protect the conversation context.
The MCP server does not retain ChatGPT conversations or Box API responses.

Disclaimer

Unofficial project. Not affiliated with, endorsed by, or supported by OpenAI or Dedale/ASCII. Users configure and operate their own ChatGPT account, OpenAI tunnel, Box account, credentials, environments, and permissions.

Use this project only for systems and resources you are authorized to access. Review the current OpenAI terms and Box terms for your use case.