greennode-code-interpreter-mcp

A stdio MCP server that gives an agent exactly one remote code-execution sandbox session per agent session: execute Python code, run shell commands, and read/write files inside a remote sandbox micro-VM.

The code interpreter (the provisioned micro-VM runtime) is external and shared — it is created and destroyed out-of-band, never by this MCP. The MCP only targets an existing, ACTIVE interpreter (by id or name) and manages disposable sessions inside it.

Singleton model

• One stdio MCP process = one agent session. The MCP process is the session identity.
• The MCP holds at most one active sandbox session at a time (enforced in-process — no locking, by construction).
• The only way to get a new session while one exists is reset_session (atomic delete-then-create; yields a fresh micro-VM). Teardown only ever destroys the session, never the shared interpreter.

Quick start

npm install
# dev (from source):
GREENNODE_CODE_INTERPRETER_TOKEN=... CODE_INTERPRETER_ID=interpreter-... npm run dev
# or compiled:
npm run compile && CODE_INTERPRETER_ID=interpreter-... npm start

Claude Code (.mcp.json)

{
  "mcpServers": {
    "greennode-code-interpreter": {
      "command": "npx",
      "args": ["-y", "@watermelonpm/greennode-code-interpreter-mcp"],
      "env": {
        "GREENNODE_CODE_INTERPRETER_TOKEN": "your-token",
        "CODE_INTERPRETER_ID": "interpreter-abc123"
      }
    }
  }
}

Tools (12)

| Tool | What it does | |---|---| | create_sandbox | Ensure one session is active (idempotent; polls interpreter to ACTIVE if still CREATING). | | reset_session | Atomic teardown + new session (fresh micro-VM). | | teardown_session | Tear down the current session (interpreter kept). | | sandbox_status | Current state + ids. | | list_interpreters | List your interpreters (read-only; for discovery). | | execute_code | Run Python code → {output}. | | execute_command | Run a shell command → {output}. | | write_file | Write one file (content or base64 data). | | read_file | Read one file → base64 resource block + size. | | list_files | List a directory. | | start_command | Start a background shell command (for >30s work) → taskId. | | get_task | Poll a background command → status + output. |

Configuration

See .env.example for all env vars. Key ones:

• BACKEND_URL — gateway base URL (placeholder prod default; set for dev).
• GREENNODE_CODE_INTERPRETER_TOKEN / TOKEN_ENV — stdio bearer (pass-through).
• CODE_INTERPRETER_ID (wins) / CODE_INTERPRETER_NAME — target an existing interpreter.
• CREATE_TIMEOUT_MS, POLL_INTERVAL_MS — interpreter poll-to-ACTIVE budget.
• MAX_FILE_BYTES (8 MiB), MAX_OUTPUT_BYTES (1 MiB) — size caps.
• LOG_LEVEL — stderr-only.

Development

| Script | Purpose | |---|---| | npm run dev | tsx watch src/index.ts | | npm run build | tsc --noEmit (typecheck) | | npm run compile | emit to dist/ | | npm test | vitest run | | npm start | node dist/index.js |