{"_id":"mcp-server-docker","name":"mcp-server-docker","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"mcp-server-docker","version":"1.0.0","description":"MCP server for executing commands in Docker containers","main":"dist/index.js","type":"module","bin":{"mcp-server-docker":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","start":"node dist/index.js","test":"jest","prepublishOnly":"npm run build"},"keywords":["mcp","docker","model-context-protocol","cli","container"],"author":{"name":"adamdude828"},"homepage":"https://github.com/adamdude828/mcp-server-docker#readme","repository":{"type":"git","url":"git+https://github.com/adamdude828/mcp-server-docker.git"},"bugs":{"url":"https://github.com/adamdude828/mcp-server-docker/issues"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^0.6.0","dotenv":"^16.4.5","express":"^4.18.2","uuid":"^9.0.1"},"devDependencies":{"@types/node":"^20.11.0","@types/express":"^4.17.21","@types/uuid":"^9.0.7","tsx":"^4.7.0","typescript":"^5.3.3","jest":"^29.7.0","@types/jest":"^29.5.11"},"_id":"mcp-server-docker@1.0.0","gitHead":"732a5c7476fe07f7bec5fe7540c929ca7600a1d4","types":"./dist/index.d.ts","_nodeVersion":"18.20.4","_npmVersion":"10.7.0","dist":{"integrity":"sha512-7uMiuUVOkxtn9fhD8vatYjWB2J7yEM4alIAhhORj28mBoQIld+wjUx21HKIsL1SyZa+EKiv4vZaiBLmoWSJWPA==","shasum":"41f36512c415597f3593cd7dd85ae7ae8a3c21ac","tarball":"https://registry.npmjs.org/mcp-server-docker/-/mcp-server-docker-1.0.0.tgz","fileCount":7,"unpackedSize":16299,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBJgexI+6VSgqOqLX18L0E3IDtbSlSvVZknMDWehLwGwAiAudkhS9zidpobDlfq128mcFJgQWvNBZRslqCf12ovk9Q=="}]},"_npmUser":{"name":"aholsinger","email":"adamdude828@gmail.com"},"directories":{},"maintainers":[{"name":"aholsinger","email":"adamdude828@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-docker_1.0.0_1750025448354_0.5849398857175163"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-15T22:10:48.352Z","1.0.0":"2025-06-15T22:10:48.539Z","modified":"2025-06-15T22:10:48.819Z"},"maintainers":[{"name":"aholsinger","email":"adamdude828@gmail.com"}],"description":"MCP server for executing commands in Docker containers","homepage":"https://github.com/adamdude828/mcp-server-docker#readme","keywords":["mcp","docker","model-context-protocol","cli","container"],"repository":{"type":"git","url":"git+https://github.com/adamdude828/mcp-server-docker.git"},"author":{"name":"adamdude828"},"bugs":{"url":"https://github.com/adamdude828/mcp-server-docker/issues"},"license":"MIT","readme":"# MCP Server: Docker Command Runner\n\nThis MCP (Model Context Protocol) server provides a secure interface for running commands inside Docker containers. It acts as a privileged sidecar that can execute arbitrary commands within specified Docker Compose service containers.\n\n## Features\n\n- STDIO-based MCP transport for integration with Claude and other MCP clients\n- Execute commands in any Docker Compose service container\n- Real-time capture of stdout/stderr output\n- Secure container allowlist configuration\n- Configurable timeouts for long-running commands\n- Clear error messages for common Docker issues\n- Minimal dependencies and secure by design\n\n## Installation\n\n### Via NPX (Recommended)\n\nRun the MCP server directly without cloning:\n\n```bash\nnpx mcp-server-docker\n```\n\nOr install globally:\n\n```bash\nnpm install -g mcp-server-docker\nmcp-server-docker\n```\n\n### As a Docker Service\n\nAdd the following to your `docker-compose.yml`:\n\n```yaml\nservices:\n  mcp-docker:\n    build: ./mcp-server-docker\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n    ports:\n      - \"3001:3000\"  # Expose MCP server\n    environment:\n      - COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME}\n      - DEFAULT_SERVICE=app\n      - COMPOSE_FILE=docker-compose.yml\n      - PORT=3000\n    networks:\n      - your-network\n```\n\n### For Local Development\n\n```bash\ncd mcp-server-docker\nnpm install\nnpm run build\n```\n\n## Configuration\n\nThe server accepts the following environment variables:\n\n- `ALLOWED_CONTAINERS`: Comma-separated list of allowed service:container pairs (e.g., \"app:myapp_container,db:mydb_container\")\n- `DEFAULT_SERVICE`: Default service to run commands in (default: \"laravel_app\")\n- `COMMAND_TIMEOUT`: Command timeout in milliseconds (default: 300000)\n\n## MCP Tool: run_command\n\nThe server exposes a single tool called `run_command`:\n\n### Input Schema\n\n```json\n{\n  \"command\": \"string (required) - The command to execute\",\n  \"service\": \"string (optional) - Docker service name\"\n}\n```\n\n### Example Usage\n\n```json\n{\n  \"command\": \"npm test\",\n  \"service\": \"frontend\"\n}\n```\n\n### Response Format\n\nThe tool returns the command output with the following structure:\n- Standard output (if any)\n- Standard error (if any, prefixed with [stderr])\n- Exit code\n\n## Usage\n\nThe server uses STDIO transport for MCP communication. When run with `npx mcp-server-docker`, it will:\n\n1. Parse environment variables for allowed containers\n2. Start the MCP server listening on stdin/stdout\n3. Log startup information to stderr\n4. Wait for MCP protocol messages\n\n## Security Notes\n\n- This server requires access to the Docker socket - ensure Docker is running and accessible\n- No command filtering is applied - relies on container isolation for security\n- Commands timeout after 5 minutes by default\n- Only allowed containers (configured via ALLOWED_CONTAINERS) can be accessed\n\n## Development\n\n```bash\n# Run in development mode\nnpm run dev\n\n# Build TypeScript\nnpm run build\n\n# Run tests\nnpm test\n```\n\n## Troubleshooting\n\n### Common Errors\n\n1. **\"Cannot connect to Docker daemon\"**: Ensure Docker is running and the socket is mounted\n2. **\"Service not found\"**: Check that the service name exists in your docker-compose.yml\n3. **\"Command timed out\"**: Command exceeded 5-minute timeout, consider breaking it into smaller operations","readmeFilename":"README.md","_rev":"1-7a3559e354806c6ca52c1cbf498a1ad0"}