chatgpt-box-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@chatgpt-box-mcp List my running boxes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 environmentsChatGPT 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 |
|
Lifecycle |
|
Work |
|
Long-running work |
|
Visual inspection |
|
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.
Related MCP server: GPT Harness
Safety model
BOX_API_KEYis 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 .envEdit .env and set:
BOX_API_KEY=box_your_secret_hereDo not commit .env.
Run locally over stdio:
npm.cmd run start:envThe 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-boxKeep 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=3000Then run:
npm.cmd run start:envEndpoints:
MCP:
http://127.0.0.1:3000/mcpHealth:
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 testThe 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_stopsnapshots before stopping unlessforce=trueis explicitly requested.Cancelling a background job sends
SIGTERMto 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.
Available Tools
15 toolsbox_createCreate Box environmentA
Provision a paid Box Linux environment owned by the configured Box account. This changes external state and starts billable runtime.
Inputs: size, no_env, ttl_seconds.
box_execute_commandExecute Box commandADestructive
Run a shell command inside a Box and wait up to 60 seconds. The command may modify files, install software, access configured credentials, or affect external systems. Use box_job_start for longer work.
Inputs: box_id (required), command (required), cwd, timeout_seconds.
box_forkFork BoxA
Create a new paid Box from an existing snapshot. The source Box is not modified.
Inputs: box_id (required), size, no_env.
box_getGet Box environmentARead-only
Inspect one Box environment after create, stop, resume, or fork operations.
Inputs: box_id (required).
box_job_cancelCancel background jobADestructive
Send SIGTERM to a running background job and its process group. Partial file or external changes are not rolled back.
Inputs: box_id (required), job_id (required).
box_job_logsRead background job logsBRead-only
Read the tails of stdout and stderr for a background job.
Inputs: box_id (required), job_id (required), max_characters.
box_job_startStart background jobADestructive
Start a long-running shell job in a Box. The job runs independently after this tool returns and may modify the machine or external systems.
Inputs: box_id (required), command (required), cwd.
box_job_statusGet background job statusARead-only
Check whether a background job is running, succeeded, failed, or was cancelled.
Inputs: box_id (required), job_id (required).
box_listList Box environmentsARead-only
Find the user's Box environments and inspect their current lifecycle states.
Inputs: sort, limit, state, cursor.
box_list_eventsList Box eventsCRead-only
Inspect recent lifecycle and work events emitted by a Box.
Inputs: box_id (required), sort, type, limit, +1 more.
box_open_desktopOpen Box desktopA
Create a secret-bearing desktop streaming URL for the user to inspect the Box. Do not log, persist, or share the returned URL.
Inputs: box_id (required), public_access.
box_read_fileRead Box fileBRead-only
Read a file relative to the Box work directory. Results are capped for model safety.
Inputs: path (required), box_id (required), encoding, max_characters.
box_resumeResume BoxA
Resume an archived Box, restarting billable runtime on a fresh machine.
Inputs: box_id (required), size, no_env.
box_stopStop and archive BoxADestructive
Stop a Box and snapshot its disk. force=true may irreversibly lose changes since the last successful snapshot and should only follow a refused normal stop.
Inputs: box_id (required), force.
box_write_fileWrite Box fileADestructive
Create or replace a file relative to the Box work directory. Existing content at the path is overwritten.
Inputs: path (required), box_id (required), content (required), encoding.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct aspect of Box management: lifecycle operations (list, get, create, stop, resume, fork), file operations (read, write), command execution (execute_command, job_start), job monitoring (status, logs, cancel), plus events and desktop access. No two tools overlap in purpose.
All tools follow a consistent box_verb_noun pattern, e.g., box_list, box_create, box_read_file, box_job_status. The naming is uniform and predictable, making it easy to infer what each tool does from its name alone.
15 tools is a well-scoped count for a full-featured Box management server. Each tool covers a distinct necessary functionality without bloat, staying within the ideal range for a comprehensive tool set.
The tool set covers the full lifecycle of a Box environment including creation, inspection, stopping, resuming, and forking, plus file operations, command execution, background job management, events, and desktop access. No obvious gaps are present for the stated domain.
Maintenance
Related MCP Connectors
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Hosted MySQL MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI assistants the ability to create, manage, and control terminal sessions through a safe, isolated tmux environment.1ISC
- AlicenseNot gradedqualityBmaintenanceA self-hosted MCP gateway that gives ChatGPT Web real command execution, file patching, and workspace management on a VPS you control.4MIT
- FlicenseNot gradedqualityBmaintenanceA self-hosted MCP server that gives ChatGPT controlled access to a user's Oracle Cloud Ubuntu VM through tools for shell commands, file operations, and personal skills.-
- FlicenseAqualityCmaintenancePrivate MCP server exposing the ascii Box API as shell and file tools, letting agents like ChatGPT or Claude drive Linux boxes.14-