{"_id":"@arxndev/container-mcp","name":"@arxndev/container-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@arxndev/container-mcp","version":"0.1.0","description":"MCP server for Apple container — manage Linux containers on macOS via AI","type":"module","bin":{"container-mcp":"dist/index.js"},"main":"./dist/index.cjs","module":"./dist/index.js","exports":{".":{"import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","dev":"tsx src/index.ts","lint":"eslint src/ tests/","format":"prettier --write .","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"keywords":["mcp","apple-container","containers","macos","ai-tools","claude","model-context-protocol","linux-containers","apple-silicon"],"author":"","license":"Apache-2.0","engines":{"node":">=18"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","execa":"^9.5.3","zod":"^3.25.67"},"devDependencies":{"@types/node":"^22.15.30","@typescript-eslint/eslint-plugin":"^8.34.0","@typescript-eslint/parser":"^8.34.0","eslint":"^9.28.0","prettier":"^3.5.3","tsup":"^8.5.0","tsx":"^4.20.3","typescript":"^5.8.3","vitest":"^3.2.3","@vitest/coverage-v8":"^3.2.3"},"_id":"@arxndev/container-mcp@0.1.0","gitHead":"1ce332e493d60748239304171d367d4075598721","types":"./dist/index.d.ts","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-/7ZVESFizjgqTtLio9iKihxvBnxVQrtri2I0hBnQ6ctVzLjmXtV5j81tFTpTCvi7DjFrkctjTc4Mg7FD0M6A4Q==","shasum":"c232c3882a8e51e563a0e2f8c614cfdaeac891e6","tarball":"https://registry.npmjs.org/@arxndev/container-mcp/-/container-mcp-0.1.0.tgz","fileCount":9,"unpackedSize":539236,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC5E4hc7PAUbF7YYAAZX6pfftOF3Mb6igcugHVFixu7qAIhAOBwEG9QhQXvivo8/WNOcPRD5dakatoFEY/5SEW5Gpar"}]},"_npmUser":{"name":"arxndev","email":"iarunrao01@gmail.com"},"directories":{},"maintainers":[{"name":"arxndev","email":"iarunrao01@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/container-mcp_0.1.0_1781268911238_0.3378051018585695"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-12T12:55:11.088Z","0.1.0":"2026-06-12T12:55:11.389Z","modified":"2026-06-12T12:55:11.643Z"},"maintainers":[{"name":"arxndev","email":"iarunrao01@gmail.com"}],"description":"MCP server for Apple container — manage Linux containers on macOS via AI","keywords":["mcp","apple-container","containers","macos","ai-tools","claude","model-context-protocol","linux-containers","apple-silicon"],"license":"Apache-2.0","readme":"# container-mcp\n\n[![npm version](https://img.shields.io/npm/v/container-mcp.svg)](https://www.npmjs.com/package/container-mcp)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)\n\n**MCP server for Apple container** — manage, build, inspect, and diagnose Linux containers on macOS directly from AI agents like Claude Desktop, Claude Code, and Cursor.\n\nBuilt on [Apple's container CLI](https://github.com/apple/container) for native Linux container support on Apple Silicon Macs.\n\n---\n\n## Prerequisites\n\n- **macOS 26+** (Tahoe) on **Apple Silicon** (M1/M2/M3/M4)\n- **Apple container CLI** installed — [github.com/apple/container](https://github.com/apple/container)\n- **Node.js 18+**\n\n## Installation\n\n```bash\nnpm install -g container-mcp\n```\n\nOr run directly with npx:\n\n```bash\nnpx container-mcp\n```\n\n## Configuration\n\n### Claude Desktop\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"container\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"container-mcp\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add container-mcp -- npx -y container-mcp\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"container\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"container-mcp\"]\n    }\n  }\n}\n```\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CONTAINER_CLI_PATH` | `container` | Path to the container CLI binary |\n| `CONTAINER_MCP_LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |\n| `CONTAINER_MCP_VOLUME_ROOT` | `$HOME` | Restricts host paths for volume mounts and file copies. Paths outside this root are rejected. |\n| `CONTAINER_MCP_CONTEXT_ROOT` | `$HOME` | Restricts the build context path for `build_image`. Paths outside this root are rejected. |\n\n---\n\n## Tool Reference\n\n### 🐳 Container Lifecycle (14 tools)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `list_containers` | List all containers | `all`, `format` |\n| `run_container` | Create & run a new container | `image`, `name`, `ports`, `env`, `volumes`, `detach`, `command` |\n| `stop_container` | Stop running containers | `names`, `timeout` |\n| `start_container` | Start stopped containers | `names` |\n| `delete_container` | Remove containers | `names`, `force` |\n| `inspect_container` | Get detailed container info | `name` |\n| `exec_in_container` | Execute command in container | `name`, `command`, `interactive` |\n| `container_commit` | Commit container to new image | `container`, `image`, `message` |\n| `copy_to_container` | Copy file/dir from host to container | `hostPath`, `containerName`, `containerPath` |\n| `copy_from_container` | Copy file/dir from container to host | `containerName`, `containerPath`, `hostPath` |\n| `wait_container` | Wait for container stop, get exit code | `name`, `timeout` |\n| `rename_container` | Rename an existing container | `container`, `newName` |\n| `pause_container` | Pause processes in containers | `names` |\n| `unpause_container` | Unpause processes in containers | `names` |\n\n### 📦 Image Management (7 tools)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `list_images` | List local images | `format` |\n| `pull_image` | Pull image from registry | `reference` |\n| `build_image` | Build image from Dockerfile | `context`, `tag`, `dockerfile`, `buildArgs`, `platform` |\n| `remove_image` | Remove images | `references`, `force` |\n| `inspect_image` | Get detailed image info | `reference` |\n| `tag_image` | Tag an existing local image | `source`, `target` |\n| `push_image` | Push image to registry | `image` |\n\n### 📋 Logs & Monitoring (3 tools)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `get_logs` | Get container logs | `name`, `tail`, `since` |\n| `get_container_stats` | Get CPU/memory/network stats | `name` |\n| `get_container_processes` | List processes in container | `name` |\n\n### 💾 Volumes (3 tools)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `list_volumes` | List all volumes | `format` |\n| `create_volume` | Create a new volume | `name`, `size` |\n| `delete_volume` | Remove volumes | `names`, `force` |\n\n### 🌐 Networks (3 tools)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `create_network` | Create a container network | `name`, `driver`, `options` |\n| `delete_network` | Remove one or more networks | `networks` |\n| `list_networks` | List all networks | `format` |\n\n### ⚙️ System (2 tools)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `system_info` | Get system info & version | — |\n| `system_prune` | Remove all unused resources | `confirm` (must be `true`) |\n\n### 🤖 AI-Powered Diagnostics (2 tools)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `diagnose_container` | Analyze logs & inspect data for issues | `name` |\n| `explain_container` | Human-readable container summary | `name` |\n\n---\n\n## Example Prompts\n\nHere are natural language prompts you can use with Claude or any MCP-compatible AI:\n\n```\n\"List all my running containers\"\n\n\"Run an nginx container named web-server on port 8080\"\n\n\"Why is my database container crashing?\"\n\n\"Show me the logs from the api container\"\n\n\"Pull the latest Ubuntu image and run a container with it\"\n\n\"What's the memory usage of all running containers?\"\n\n\"Explain what the postgres container is doing\"\n\n\"Build a Docker image from the current directory and tag it myapp:latest\"\n\n\"Stop all containers and clean up unused images\"\n\n\"Diagnose why the redis container keeps restarting\"\n```\n\n---\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/your-org/container-mcp.git\ncd container-mcp\nnpm install\n```\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Test\n\n```bash\nnpm test\nnpm run test:coverage\n```\n\n### Run locally\n\n```bash\nnpm run dev\n```\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/my-feature`\n3. Write code and tests\n4. Ensure tests pass: `npm test`\n5. Ensure the build works: `npm run build`\n6. Submit a Pull Request\n\n### Code Style\n\n- TypeScript strict mode\n- ESM modules\n- Prettier + ESLint for formatting\n- Zod schemas for all input validation\n- JSDoc comments on all exported functions\n\n---\n\n## Architecture\n\n```\ncontainer-mcp\n├── MCP Server (stdio transport)\n│   ├── Container Tools (8) ── container CLI\n│   ├── Image Tools (5) ────── container CLI\n│   ├── Log Tools (3) ──────── container CLI\n│   ├── Volume Tools (3) ───── container CLI\n│   ├── Network Tools (1) ──── container CLI\n│   ├── System Tools (2) ───── container CLI\n│   └── AI Tools (2) ──────── combines multiple CLI calls\n│       ├── diagnose_container → logs + inspect → pattern analysis\n│       └── explain_container  → inspect + stats + top → summary\n└── Utilities\n    ├── CLI Executor (execa, safe args)\n    ├── Output Parsers (JSON, table)\n    └── Logger (structured, stderr)\n```\n\n---\n\n## License\n\n[Apache-2.0](./LICENSE)\n","readmeFilename":"README.md","_rev":"1-15ffeb60dfa2aa000ce29f436cb3631e"}