Skip to content
Back to search

che-container-mcp

MCP server for Linux container jobs (including long CI runs) via Apple's container CLI

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/psychquant--che-container-mcp/badge.svg)](/listings/psychquant--che-container-mcp)

HTML

<a href="/listings/psychquant--che-container-mcp"><img src="/api/listings/psychquant--che-container-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code (the plugin downloads the notarized binary to `~/bin/CheContainerMCP` on first use, at the version the plugin pins):

/plugin install che-container-mcp --marketplace PsychQuant/che-container-mcp

On older Claude Code: `/plugin marketplace add PsychQuant/che-container-mcp`, then `/plugin install che-container-mcp@che-container-mcp`.

The plugin adds the MCP server (tools appear as `mcp__plugin_che-container-mcp_container__*`), a `container-jobs` skill, a `/container-status` command and a SessionStart status line. Claude Desktop: install the `.mcpb` from the release.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "che-container-mcp",
  4. "description": "Linux container jobs over MCP through Apple's container CLI — self-hosted marketplace co-located with the binary source.",
  5. "owner": {
  6. "name": "Che Cheng"
  7. },
  8. "plugins": [
  9. {
  10. "name": "che-container-mcp",
  11. "version": "0.1.0",
  12. "description": "Apple container MCP Server - 7 個工具跑 Linux 容器工作(含長時間 CI):立即回傳 job id、狀態落盤跨重啟、exit code 記錄、原始碼唯讀掛載、job 期間防閒置睡眠、Docker 只在單次授權時使用",
  13. "author": {
  14. "name": "Che Cheng"
  15. },
  16. "source": "./plugin",
  17. "category": "development"
  18. }
  19. ]
  20. }
README.md · README · 122 lines
  1. # che-container-mcp
  2. An MCP server that runs Linux container jobs — including ones far longer than a tool call — through Apple's [`container`](https://github.com/apple/container) CLI. No Docker Desktop needed.
  3. - Start a job and get a `job_id` back at once; wait, read the result or cancel later.
  4. - Job state lives on disk, so jobs survive a restart of the server (or of Claude).
  5. - The source directory is mounted read-only by default; the output directory is writable.
  6. - While a job runs, the server keeps the Mac from idle-sleeping and reports whether it slept anyway.
  7. - Docker is used only when one `container_run` call explicitly authorizes it and `container` is unavailable.
  8. Tested with `container` **1.7.1** on macOS 26 (Apple Silicon). The CLI's JSON output is still changing between 1.x releases; unknown fields are ignored and a missing required field returns `cli_output_unexpected` with the CLI version.
  9. ## Install
  10. Claude Code (the plugin downloads the notarized binary to `~/bin/CheContainerMCP` on first use, at the version the plugin pins):
  11. ```bash
  12. /plugin install che-container-mcp --marketplace PsychQuant/che-container-mcp
  13. ```
  14. On older Claude Code: `/plugin marketplace add PsychQuant/che-container-mcp`, then `/plugin install che-container-mcp@che-container-mcp`.
  15. The plugin adds the MCP server (tools appear as `mcp__plugin_che-container-mcp_container__*`), a `container-jobs` skill, a `/container-status` command and a SessionStart status line. Claude Desktop: install the `.mcpb` from the release.
  16. ## Requirements
  17. - macOS 26 on Apple Silicon, with the `container` CLI installed at `/usr/local/bin/container` (or set `container_path`).
  18. - The service started once (`container system start`, or call `container_status` with `start: true`).
  19. - **Images must contain `/bin/sh`.** Every job runs as `/bin/sh -c <wrapper> che-job <command…>`: the wrapper records the exit code (Apple's `container inspect` does not report one). The image's own `ENTRYPOINT` is replaced, so put the full command in `command`.
  20. ## Tools
  21. | Tool | Input | Output |
  22. |---|---|---|
  23. | `container_status` | `start?` (default false) | `cli_path`, `client_version`, `server_version`, `status` (`running`/`stopped`/`unavailable`), `kernel_installed` (`true`/`false`/`"unknown"`), `started_now` |
  24. | `container_image_ensure` | `image`, `platform?` | `image` (normalized, e.g. `docker.io/library/swift:6.0.3-noble`), `state` (`present`/`pulled`/`pulling`), `digest`, `size_bytes` |
  25. | `container_run` | `image`, `command` (array), `source_dir?`, `source_writable?`, `output_dir?`, `cpus?`, `memory?`, `workdir?`, `env?`, `allow_docker?` | `job_id`, `container_name`, `runtime`, `state: "running"`, `started_at`, `mounts` |
  26. | `container_job_status` | `job_id?` (omit for all jobs) | `state`, `runtime`, `image`, `started_at`, `ended_at`, `elapsed_seconds`; running jobs add `tail` (last 20 lines) |
  27. | `container_job_wait` | `job_id`, `timeout_seconds?` (1–600, default 120) | status fields + `timed_out`, `waited_seconds`. A timeout is **not** an error |
  28. | `container_job_result` | `job_id`, `tail_lines?` (1–1000, default 50), `keep_container?` | `exit_code`, `exit_code_source` (`file`/`log_marker`/`none`), `elapsed_seconds`, `tail`, `log_path`, `host_slept_during_job` (`true`/`false`/`"unknown"`), `sleep_events`, `container_deleted` |
  29. | `container_job_cancel` | `job_id`, `grace_seconds?` (0–300, default 10) | `state`, `container_deleted`, `log_path` |
  30. Every result carries `runtime` (`container` or `docker`). Errors come back as `{"error": {"code", "message"}}` with one of: `runtime_unavailable`, `kernel_missing`, `image_not_found`, `invalid_mount`, `invalid_argument`, `config_invalid`, `job_not_found`, `job_not_finished`, `cli_timeout`, `cli_failed`, `cli_output_unexpected`, `docker_unavailable`.
  31. Job states: `running`, `exited`, `exited_unknown` (stopped, exit code not recoverable), `cancelled`, `lost` (container gone, no exit code), `failed_to_start`.
  32. ### Typical CI run
  33. ```text
  34. container_image_ensure {"image": "swift:6.0.3-noble"}
  35. container_run {"image": "swift:6.0.3-noble", "command": ["sh", "-c", "./ci.sh"],
  36. "source_dir": "/path/to/repo", "output_dir": "/path/to/ci-out"}
  37. container_job_wait {"job_id": "cj-…", "timeout_seconds": 600} # repeat until timed_out is false
  38. container_job_result {"job_id": "cj-…", "tail_lines": 100}
  39. ```
  40. ### What runs before a container starts
  41. `container_run` checks, in order: the config file, the CLI, that the service is running, the kernel, that the image is local (it never pulls), and the mounts. Any failure returns its error and starts nothing.
  42. ## Mounts
  43. - `source_dir` → `/src`, read-only unless `source_writable: true`. `output_dir` → `/out`, writable. Working directory defaults to `/src`.
  44. - Paths are resolved with `realpath` first. Rejected with `invalid_mount`: relative paths, missing paths, non-directories, `/`, your home directory itself, source and output nested in either direction (including through a symlink), paths inside the server's state directory, and paths containing a comma.
  45. - `env` takes explicit `{"KEY": "value"}` pairs only. Host variables are never inherited; `--env-file`, `--secret` and `--ssh` are not supported. Job records keep the keys, not the values.
  46. ## Config
  47. Optional `~/Library/Application Support/che-container-mcp/config.json` (or `$CHE_CONTAINER_MCP_HOME/config.json`):
  48. ```json
  49. {
  50. "container_path": "/usr/local/bin/container",
  51. "docker_path": "/usr/local/bin/docker",
  52. "defaults": {
  53. "source_dir": "/path/to/repo",
  54. "output_dir": "/path/to/ci-out",
  55. "cpus": 8,
  56. "memory": "16G",
  57. "source_mount": "/src",
  58. "output_mount": "/out",
  59. "workdir": "/src"
  60. }
  61. }
  62. ```
  63. Built-in defaults: 8 CPUs, 16G memory, `/src`, `/out`. A malformed file makes every tool return `config_invalid` — it never silently falls back.
  64. ## Job records
  65. Each job has `jobs/<job_id>/` under the state directory: `job.json` (the record, written atomically), `state/` (mounted at `/.che-job` for the exit code) and `output.log` (the full log, copied when the job finishes and before its container is deleted). Records are never removed automatically; delete finished job directories by hand when you no longer need them.
  66. ## Sleep
  67. Apple's container VMs pause when the Mac sleeps, so a 40-minute CI run can stretch to hours. While any job runs, the server holds a `PreventUserIdleSystemSleep` assertion (the same kind as `caffeinate -i`) and records sleep/wake events.
  68. - This assertion does **not** prevent closing the lid or Maintenance Sleep. For long jobs, keep the Mac on power with the lid open.
  69. - The assertion lives only while the server process runs. If the server was not running for part of a job, `host_slept_during_job` is `"unknown"`, so you know an elapsed time is not comparable.
  70. ## Known issues
  71. - Large downloads inside a container have been seen to stall (DNS and TCP fine, transfer stopped) while the same file downloads quickly on the host. Download large dependencies on the host into the source or output directory and mount them.
  72. ## Docker
  73. Pass `allow_docker: true` to one `container_run` call. Docker is used only if `container` is unavailable (CLI missing or service not running); the authorization is not stored and covers only that call. Later status, wait, result and cancel calls for that job use Docker automatically. When `container` is available, `allow_docker` changes nothing.
  74. ## Build and test
  75. ```bash
  76. make build # debug build
  77. make test # unit tests (live tests are skipped)
  78. make test-live # integration tests against the real container service
  79. DEVELOPER_ID=… NOTARY_PROFILE=… make release-signed # universal, signed, notarized, packed
  80. DEVELOPER_ID=… make release-signed-local # same, without notarization
  81. ```
  82. CLI mode for scripts: `CheContainerMCP --cli container_status` or `CheContainerMCP --cli container_run '{"image": "…", "command": ["true"]}'`.
  83. ## License
  84. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.