{"_id":"@democratize-technology/claude-code-container-mcp","name":"@democratize-technology/claude-code-container-mcp","dist-tags":{"latest":"3.0.0"},"versions":{"3.0.0":{"name":"@democratize-technology/claude-code-container-mcp","version":"3.0.0","description":"MCP server for containerized Claude Code session management","author":{"name":"democratize-technology","url":"forked from Peter Steinberger"},"license":"MIT","main":"dist/container-server.js","bin":{"claude-code-container-mcp":"dist/container-server.js"},"scripts":{"build":"tsc","start":"node dist/container-server.js","dev":"tsx src/container-server.ts","test":"npm run build && vitest","test:unit":"vitest run --config vitest.config.unit.ts","test:e2e":"npm run build && vitest run --config vitest.config.e2e.ts","test:coverage":"npm run build && vitest --coverage --config vitest.config.unit.ts","test:watch":"vitest --watch","postinstall":"npm run build || echo 'Build failed, continuing...'"},"dependencies":{"@modelcontextprotocol/sdk":"^1.11.2","dockerode":"^4.0.2","uuid":"^9.0.1","zod":"^3.24.4"},"type":"module","devDependencies":{"@eslint/js":"^9.26.0","@types/dockerode":"^3.3.31","@types/node":"^22.15.17","@types/uuid":"^9.0.8","@vitest/coverage-v8":"^2.1.8","tsx":"^4.19.4","typescript":"^5.8.3","vitest":"^2.1.8"},"repository":{"type":"git","url":"git+https://github.com/democratize-technology/claude-code-mcp.git"},"keywords":["mcp","model-context-protocol","claude","ai","llm","tools","docker","container"],"bugs":{"url":"https://github.com/democratize-technology/claude-code-mcp/issues"},"publishConfig":{"access":"public"},"homepage":"https://github.com/democratize-technology/claude-code-mcp#readme","_id":"@democratize-technology/claude-code-container-mcp@3.0.0","gitHead":"fbd46c31bf63d6e0196b6df4320d4b35f243ef3a","types":"./dist/container-server.d.ts","_nodeVersion":"20.19.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-dMLB6qMygj/slor5DDggQhDsk3tucPGlwUV2H9CaCxZ9HDVxKl6DQrMAXBRGK0WlPO8SjJYeZrrdJMmB7ji1Ng==","shasum":"c3755e186a657acef1d925aea003d07d578620ec","tarball":"https://registry.npmjs.org/@democratize-technology/claude-code-container-mcp/-/claude-code-container-mcp-3.0.0.tgz","fileCount":36,"unpackedSize":115688,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAq+s8JvCdEa7VhxhFAZt7BAxhks+agHGHZSqWUMT/VFAiBnofi92IO/U33lAQ2unRHLMji9tITf0d41sqSivBq0KQ=="}]},"_npmUser":{"name":"jeremy-green","email":"hello@jeremy.green","actor":{"name":"jeremy-green","email":"hello@jeremy.green","type":"user"}},"directories":{},"maintainers":[{"name":"jeremy-green","email":"hello@jeremy.green"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-code-container-mcp_3.0.0_1751822789656_0.8724715607477465"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-06T17:26:29.512Z","3.0.0":"2025-07-06T17:26:29.859Z","modified":"2025-07-06T17:26:30.240Z"},"maintainers":[{"name":"jeremy-green","email":"hello@jeremy.green"}],"description":"MCP server for containerized Claude Code session management","homepage":"https://github.com/democratize-technology/claude-code-mcp#readme","keywords":["mcp","model-context-protocol","claude","ai","llm","tools","docker","container"],"repository":{"type":"git","url":"git+https://github.com/democratize-technology/claude-code-mcp.git"},"author":{"name":"democratize-technology","url":"forked from Peter Steinberger"},"bugs":{"url":"https://github.com/democratize-technology/claude-code-mcp/issues"},"license":"MIT","readme":"# Claude Code Container MCP Server\n\n> Transform Claude Code from a CLI tool into an orchestratable service through the Model Context Protocol\n\nAn MCP (Model Context Protocol) server that manages containerized Claude Code sessions, enabling AI assistants to create and control isolated Claude Code instances programmatically. Unlike simple containerization solutions, this provides a clean API for AI-to-AI workflows and enterprise integrations.\n\n## ⚠️ Legal Notice\n\nThis is an unofficial containerization of Claude Code. Users are responsible for compliance with [Anthropic's Terms of Service](https://www.anthropic.com/legal/commercial-terms). By using this software, you acknowledge that you have read and agreed to Anthropic's terms.\n\n## Features\n\n- 🐳 **Docker-based Isolation**: Each Claude Code instance runs in its own container\n- 🔄 **Session Management**: Create, execute, and destroy Claude Code sessions\n- 📁 **Volume Mounting**: Persistent storage for project files\n- 🔒 **Security**: Container isolation protects the host system\n- 🚀 **Scalability**: Run multiple sessions simultaneously\n- 🛠️ **Extended Tools**: File transfer, command execution, and log access\n- ☁️ **AWS Bedrock Support**: Use Claude through AWS Bedrock for enterprise deployments\n- 🔑 **Flexible Authentication**: Support for both Anthropic API keys and AWS credentials\n\n## Real-World Use Cases\n\n### 1. Parallel Development Workflows\n```javascript\n// Create sessions for different microservices\nconst frontend = await createSession({ projectPath: '/app/frontend' });\nconst backend = await createSession({ projectPath: '/app/backend' });\n\n// Work on both simultaneously\nawait executeInSession({ \n  sessionId: frontend.id, \n  prompt: 'Update React components to use new design system' \n});\nawait executeInSession({ \n  sessionId: backend.id, \n  prompt: 'Implement new REST endpoints for user management' \n});\n```\n\n### 2. Automated Code Reviews\n```javascript\n// Pull request review workflow\nconst session = await createSession({ projectPath: '/tmp/pr-1234' });\nconst review = await executeInSession({\n  sessionId: session.id,\n  prompt: 'Review this code for security vulnerabilities and performance issues'\n});\n// Post review comments back to GitHub\n```\n\n### 3. Enterprise Batch Operations\n```javascript\n// Update multiple projects with new security policy\nfor (const project of projects) {\n  const session = await createSession({ \n    projectPath: project.path,\n    useBedrock: true,\n    awsRegion: 'us-east-1'\n  });\n  await executeInSession({\n    sessionId: session.id,\n    prompt: 'Update dependencies and apply new security headers'\n  });\n}\n```\n\n### 4. CI/CD Integration\n```yaml\n# GitHub Actions example\n- name: AI Code Review\n  run: |\n    npx claude-code-mcp create-session ./\n    npx claude-code-mcp execute \"Review code changes and suggest improvements\"\n```\n\n## What's Different?\n\nThis is a fork of [steipete/claude-code-mcp](https://github.com/steipete/claude-code-mcp) that adds containerization capabilities. Instead of running Claude Code directly, this server manages Docker containers running Claude Code, providing:\n\n- Better isolation between different projects\n- Ability to run multiple Claude Code instances\n- Protection of the host system\n- Easy cleanup of resources\n- Support for AWS Bedrock as an alternative to Anthropic API\n\n## Why Choose This Over Other Solutions?\n\n| Feature | claude-code-mcp<br>(This Project) | claudebox | claude-docker | Base claude-code |\n|---------|-----------------------------------|-----------|---------------|------------------|\n| **Containerization** | ✅ Full isolation | ✅ Full isolation | ✅ Full isolation | ✅ Basic |\n| **MCP Interface** | ✅ **Full API** | ❌ CLI only | ❌ CLI only | ❌ None |\n| **Multi-Session** | ✅ **Unlimited** | 🟡 Limited | ❌ Single | ❌ None |\n| **AWS Bedrock** | ✅ **Native** | ❌ No | ❌ No | ❌ No |\n| **Session API** | ✅ **Complete** | ❌ None | ❌ None | ❌ None |\n| **AI Orchestration** | ✅ **Built-in** | ❌ Manual | ❌ Manual | ❌ None |\n\n### Key Differentiator: MCP Orchestration\n\nWhile other projects focus on running Claude Code in Docker, we provide **programmatic control** through MCP:\n\n```javascript\n// Other solutions: Manual Docker commands\ndocker run -it claude-code\n\n// Our solution: Programmable API\nawait mcp.tool('create_session', { projectPath: '/app' });\nawait mcp.tool('execute_in_session', { prompt: 'refactor this code' });\n```\n\nThis enables:\n- **AI-to-AI workflows**: Claude can manage multiple Claude Code sessions\n- **CI/CD integration**: Automated code reviews and testing\n- **Enterprise automation**: Bulk operations across projects\n\n## 🔒 Security Considerations\n\n### Docker Daemon Access Required\nThis MCP server requires access to the Docker daemon, which has significant security implications:\n\n- **Root-equivalent permissions**: Docker access can be used to gain root privileges\n- **Container isolation**: While Claude Code runs isolated, the MCP server has Docker control\n- **Network security**: Containers can access network resources based on Docker configuration\n\n### Recommended Security Practices\n\n1. **Run the MCP server in a container** (double isolation):\n   ```bash\n   docker run -v /var/run/docker.sock:/var/run/docker.sock claude-code-mcp\n   ```\n\n2. **Use Docker security options**:\n   ```bash\n   --security-opt=no-new-privileges\n   --cap-drop=ALL\n   ```\n\n3. **Restrict network access** in production environments\n\n4. **Monitor container activity** and implement audit logging\n\nFor maximum security, consider running this in a dedicated VM or container host.\n\n## Prerequisites\n\n- Node.js v20 or later\n- Docker installed and running\n- Either:\n  - Anthropic API key, OR\n  - AWS credentials with Bedrock access\n\n### Building the Custom Claude Code Image\n\nTo reduce external dependencies, we provide a custom Docker image:\n\n```bash\n# Build the custom image\n./scripts/build-custom-image.sh\n\n# This creates: claude-code-custom:latest\n```\n\n## Installation\n\n### From Source (currently required)\n\n```bash\ngit clone https://github.com/democratize-technology/claude-code-container-mcp.git\ncd claude-code-container-mcp\nnpm install\nnpm run build\n```\n\n<!--\n### Using npm (coming soon)\n\n```bash\nnpm install -g @democratize-technology/claude-code-container-mcp\n```\n\n### Using Docker (coming soon)\n\n```bash\ndocker pull ghcr.io/democratize-technology/claude-code-container-mcp:latest\n```\n-->\n\n## Configuration\n\n### For Claude Desktop\n\n#### Option 1: Using Anthropic API\n\n```json\n{\n  \"claude-code-container\": {\n    \"command\": \"node\",\n    \"args\": [\"/path/to/claude-code-mcp/dist/container-server.js\"],\n    \"env\": {\n      \"ANTHROPIC_API_KEY\": \"your-api-key\"\n    }\n  }\n}\n```\n\n#### Option 2: Using AWS Bedrock\n\n```json\n{\n  \"claude-code-container\": {\n    \"command\": \"node\",\n    \"args\": [\"/path/to/claude-code-mcp/dist/container-server.js\"],\n    \"env\": {\n      \"CLAUDE_CODE_USE_BEDROCK\": \"1\",\n      \"AWS_REGION\": \"us-east-1\",\n      \"AWS_ACCESS_KEY_ID\": \"your-access-key\",\n      \"AWS_SECRET_ACCESS_KEY\": \"your-secret-key\",\n      \"ANTHROPIC_MODEL\": \"us.anthropic.claude-opus-4-20250514-v1:0\",\n      \"ANTHROPIC_SMALL_FAST_MODEL\": \"us.anthropic.claude-3-5-haiku-20241022-v1:0\"\n    }\n  }\n}\n```\n\n### For Other MCP Clients\n\nSee your client's documentation for MCP server configuration.\n\n## Available Tools\n\n### 1. `create_session`\nCreates a new Claude Code container session.\n\n**Arguments:**\n- `projectPath` (string, required): Path to mount in the container\n- `sessionName` (string, optional): Human-friendly session name\n- `apiKey` (string, optional): Anthropic API key for this session\n- `useBedrock` (boolean, optional): Use AWS Bedrock instead of Anthropic API\n- `awsRegion` (string, optional): AWS region for Bedrock\n- `awsAccessKeyId` (string, optional): AWS access key ID\n- `awsSecretAccessKey` (string, optional): AWS secret access key\n- `awsSessionToken` (string, optional): AWS session token (for temporary credentials)\n- `bedrockModel` (string, optional): Bedrock model ID\n- `bedrockSmallModel` (string, optional): Bedrock small/fast model ID\n- `mcpMounts` (array, optional): MCP server directories to mount in the container\n  - Each mount object contains:\n    - `hostPath` (string, required): Path on Docker host to mount\n    - `containerPath` (string, required): Path in container where to mount\n    - `readOnly` (boolean, optional): Mount as read-only (default: true)\n- `mcpConfig` (object, optional): MCP configuration passed to container as MCP_CONFIG environment variable\n  - **⚠️ Note**: The Claude Code container does NOT automatically process this configuration\n  - The MCP_CONFIG is set as a base64-encoded environment variable but requires manual processing\n  - Contains:\n    - `mcpServers` (object, required): MCP servers configuration\n\n### 2. `execute_in_session`\nExecutes a Claude Code command in an existing session.\n\n**Arguments:**\n- `sessionId` (string, required): Session ID\n- `prompt` (string, required): Prompt for Claude Code\n- `tools` (array of strings, optional): Specific tools to enable\n\n### 3. `list_sessions`\nLists all active sessions with their status.\n\n### 4. `destroy_session`\nDestroys a Claude Code session and removes the container.\n\n**Arguments:**\n- `sessionId` (string, required): Session ID to destroy\n\n### 5. `transfer_files`\nTransfers files between host and container.\n\n**Arguments:**\n- `sessionId` (string, required): Session ID\n- `direction` (string, required): 'to_container' or 'from_container'\n- `sourcePath` (string, required): Source path\n- `destPath` (string, required): Destination path\n\n### 6. `execute_command`\nExecutes an arbitrary command in the container.\n\n**Arguments:**\n- `sessionId` (string, required): Session ID\n- `command` (string, required): Command to execute\n\n### 7. `get_session_logs`\nRetrieves container logs for debugging.\n\n**Arguments:**\n- `sessionId` (string, required): Session ID\n- `tail` (number, optional): Number of lines to tail (default: 100)\n\n## Usage Examples\n\n### Creating a Session with Anthropic API\n```\nCreate a new Claude Code session for the project at /home/user/my-project\n```\n\n### Creating a Session with AWS Bedrock\n```\nCreate a new Claude Code session for /home/user/my-project using Bedrock with AWS region us-west-2\n```\n\n### Working with Code\n```\nIn session abc123, refactor the main.py file to use async/await\n```\n\n### Managing Sessions\n```\nList all active sessions\nDestroy session abc123\n```\n\n## MCP Configuration\n\n### Using mcpMounts\n\nThe `mcpMounts` parameter allows you to mount MCP server directories into the container:\n\n```json\n{\n  \"tool\": \"create_session\",\n  \"arguments\": {\n    \"projectPath\": \"/home/user/my-project\",\n    \"sessionName\": \"with-mcp-mounts\",\n    \"mcpMounts\": [\n      {\n        \"hostPath\": \"/opt/mcp-servers\",\n        \"containerPath\": \"/opt/mcp-servers\",\n        \"readOnly\": true\n      }\n    ]\n  }\n}\n```\n\n### Using mcpConfig\n\n⚠️ **Important**: The `mcpConfig` parameter requires a custom Docker image. The default Claude Code container does not process the `MCP_CONFIG` environment variable.\n\n#### Building the Custom Image\n\n1. Build the custom image with MCP support:\n   ```bash\n   ./scripts/build-custom-image.sh\n   ```\n\n   The custom image includes:\n   - MCP configuration processor (processes `MCP_CONFIG` environment variable)\n   - `jq` for JSON processing\n   - `uv` for Python-based MCP servers\n   - `npx` (from base image) for JavaScript/TypeScript MCP servers\n\n2. Configure your MCP server to use the custom image:\n   ```json\n   {\n     \"claude-code-container\": {\n       \"env\": {\n         \"DEFAULT_CLAUDE_IMAGE\": \"claude-code-mcp:latest\"\n       }\n     }\n   }\n   ```\n\n#### Using mcpConfig\n\nOnce the custom image is built and configured, you can pass MCP server configuration:\n\n```json\n{\n  \"tool\": \"create_session\",\n  \"arguments\": {\n    \"projectPath\": \"/home/user/my-project\",\n    \"sessionName\": \"with-mcp-config\",\n    \"mcpConfig\": {\n      \"mcpServers\": {\n        \"sequential-thinking\": {\n          \"command\": \"npx\",\n          \"args\": [\"-y\", \"@modelcontextprotocol/server-sequential-thinking\"]\n        }\n      }\n    }\n  }\n}\n```\n\n**⚠️ Important Limitation**: The Claude Code container does NOT automatically process the `MCP_CONFIG` environment variable. To use this configuration, you must manually merge it into `.claude.json` after creating the session:\n\n```bash\n# Inside the container, run:\necho $MCP_CONFIG | base64 -d | python3 -c \"\nimport json, sys\nconfig = json.load(open('/root/.claude.json'))\nmcp = json.load(sys.stdin)\nconfig['projects']['/app']['mcpServers'] = mcp['mcpServers']\njson.dump(config, open('/root/.claude.json', 'w'), indent=2)\n\"\n```\n\n## AWS Bedrock Configuration\n\n### Setting up AWS Credentials\n\nThe MCP server supports multiple ways to provide AWS credentials:\n\n1. **Environment Variables** (Global default):\n   ```bash\n   export CLAUDE_CODE_USE_BEDROCK=1\n   export AWS_REGION=us-east-1\n   export AWS_ACCESS_KEY_ID=your-key\n   export AWS_SECRET_ACCESS_KEY=your-secret\n   ```\n\n2. **Per-Session Credentials**:\n   When creating a session, you can provide specific AWS credentials that will only be used for that session.\n\n3. **IAM Roles** (if running on AWS):\n   If the MCP server is running on an EC2 instance or ECS, it can use IAM roles.\n\n### Required IAM Permissions\n\nYour AWS credentials need the following Bedrock permissions:\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"bedrock:InvokeModel\",\n        \"bedrock:InvokeModelWithResponseStream\"\n      ],\n      \"Resource\": [\n        \"arn:aws:bedrock:*::foundation-model/anthropic.claude-*\"\n      ]\n    }\n  ]\n}\n```\n\n### Model Access\n\nEnsure you have requested and been granted access to Claude models in AWS Bedrock:\n1. Go to AWS Console > Bedrock > Model access\n2. Request access to Anthropic Claude models\n3. Wait for approval (usually automatic for Claude models)\n\n## Development\n\n### Local Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/democratize-technology/claude-code-mcp.git\ncd claude-code-mcp\n\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run locally\nnpm start\n```\n\n### Using Docker Compose\n\n```bash\n# Copy environment file\ncp .env.example .env\n# Edit .env with your API key or AWS credentials\n\n# Start the service\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f mcp-server\n```\n\n## Environment Variables\n\n### General\n- `DEFAULT_CLAUDE_IMAGE`: Docker image to use (default: claude-code-custom:latest)\n- `MCP_CLAUDE_DEBUG`: Enable debug logging (true/false)\n- `DOCKER_HOST`: Docker daemon socket (default: unix:///var/run/docker.sock)\n\n### Custom Docker Image\n\nThe default base image has hardcoded `/app` paths. We provide a custom image that properly uses `/workspace`:\n\n```bash\n# Build the custom image\n./build-custom-image.sh\n\n# This creates: claude-code-custom:latest\n```\n\nIf you prefer the original image, set:\n```bash\nexport DEFAULT_CLAUDE_IMAGE=ghcr.io/zeeno-atl/claude-code:latest\n```\n\n### Anthropic API\n- `ANTHROPIC_API_KEY`: Your Anthropic API key\n\n### AWS Bedrock\n- `CLAUDE_CODE_USE_BEDROCK`: Set to \"1\" to use Bedrock by default\n- `AWS_REGION`: AWS region where Bedrock is available\n- `AWS_ACCESS_KEY_ID`: AWS access key\n- `AWS_SECRET_ACCESS_KEY`: AWS secret key\n- `AWS_SESSION_TOKEN`: AWS session token (for temporary credentials)\n- `ANTHROPIC_MODEL`: Bedrock model ID for primary model\n- `ANTHROPIC_SMALL_FAST_MODEL`: Bedrock model ID for small/fast model\n\n## Security Considerations\n\n- This server requires access to the Docker daemon, which has security implications\n- Each Claude Code instance runs in an isolated container\n- Containers have limited access to the host system\n- Always review the code Claude Code generates before executing\n- Consider running the MCP server itself in a container for additional isolation\n- When using AWS Bedrock, follow AWS security best practices for credential management\n\n## Troubleshooting\n\n### Container Creation Fails\n- Ensure Docker is running: `docker ps`\n- Check if the image is accessible: `docker pull ghcr.io/Zeeno-atl/claude-code:latest`\n- Verify your user has Docker permissions\n\n### Session Not Responding\n- Check container logs: Use the `get_session_logs` tool\n- Verify the container is running: Use `list_sessions`\n- For Anthropic API: Ensure the API key is valid\n- For AWS Bedrock: Check AWS credentials and model access\n\n### AWS Bedrock Issues\n- Verify AWS credentials: `aws sts get-caller-identity`\n- Check Bedrock model access in AWS Console\n- Ensure the AWS region supports Bedrock\n- Check IAM permissions for Bedrock InvokeModel\n\n### Permission Issues\n- The container runs with your user ID to prevent permission problems\n- Ensure the project path is accessible\n- Check Docker socket permissions\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) first.\n\n### Key areas for contribution:\n- Additional cloud provider support (Google Vertex AI, Azure)\n- Enhanced security features\n- Performance optimizations\n- Additional MCP tools\n- Documentation improvements\n\n## Roadmap\n\n### v3.0 (Current Release)\n- ✅ Complete containerization architecture\n- ✅ Multi-session management\n- ✅ AWS Bedrock support\n- ✅ Custom Docker image support\n- ✅ File transfer capabilities\n- ✅ Session logging\n\n### Future Releases\n- [ ] Comprehensive test coverage\n- [ ] Google Vertex AI support\n- [ ] Advanced session orchestration\n- [ ] Resource usage monitoring\n- [ ] Session templates\n- [ ] Kubernetes operator\n- [ ] Web UI for session management\n- [ ] Plugin system for custom tools\n\n## License\n\nMIT\n\n## Acknowledgments\n\n- Original [claude-code-mcp](https://github.com/steipete/claude-code-mcp) by Peter Steinberger - for the initial MCP implementation idea\n- [Zeeno-atl/claude-code](https://github.com/Zeeno-atl/claude-code) - for demonstrating Claude Code containerization\n- [Anthropic](https://www.anthropic.com) - for Claude and the Model Context Protocol\n- [AWS](https://aws.amazon.com) - for Bedrock service\n- Our contributors and the open source community\n\n## Support\n\n- 🐛 [Issue Tracker](https://github.com/democratize-technology/claude-code-container-mcp/issues)\n- 📖 [README](https://github.com/democratize-technology/claude-code-container-mcp#readme)\n\n---\n\nBuilt with ❤️ by [Democratize Technology](https://github.com/democratize-technology)\n","readmeFilename":"README.md","_rev":"1-e13fcbe3da4ffd78028716968ba3a3af"}