Skip to main content
Glama

ChatGPT Box MCP

English | 简体中文

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.

Related MCP server: GPT Harness

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

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

  1. Create a tunnel in OpenAI Platform tunnel settings and associate it with the ChatGPT workspace that will use it.

  2. Download the latest tunnel-client.

  3. 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.

  1. Open ChatGPT Plugins, create a developer-mode app, choose Tunnel, and select the tunnel.

  2. 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.

Available Tools

15 tools
box_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 commandA
Destructive

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 environmentA
Read-only

Inspect one Box environment after create, stop, resume, or fork operations.

Inputs: box_id (required).

box_job_cancelCancel background jobA
Destructive

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 logsB
Read-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 jobA
Destructive

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 statusA
Read-only

Check whether a background job is running, succeeded, failed, or was cancelled.

Inputs: box_id (required), job_id (required).

box_listList Box environmentsA
Read-only

Find the user's Box environments and inspect their current lifecycle states.

Inputs: sort, limit, state, cursor.

box_list_eventsList Box eventsC
Read-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 fileB
Read-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 BoxA
Destructive

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 fileA
Destructive

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

    A3.9/5.0

    Scored across 15 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers