claude-code-vm

Claude Code VM is an MCP server designed to automate the deployment of Claude Code development environments on Debian-based VMs. It exposes a structured deployment flow with multiple tiers (baseline, enhanced, containerized, and full Kubernetes) and includes a set of MCP servers that handle foundational tooling (Git, Node.js, CLAUDE CLI), container/runtime orchestration (Docker, Docker Compose), and orchestration platforms (kubectl, k3s, KIND). The system supports external configuration, multi-provider Git credentials, and secure, rule-based deployments. You can escalate from a minimal Git+Node.js setup to a full Kubernetes cluster with NGINX ingress and Kubernetes tooling, all orchestrated through Ansible with a Makefile interface. The available tooling spans provider credential management, AI-enabled MCP servers (some requiring API keys), and environment-ready wrappers for shell productivity (aliases and advanced functions) once you deploy locally or to a target VM.

Prerequisites:\n- A machine running Debian 12+ (Bookworm) or a compatible target VM.\n- Ansible 2.9+ installed on the control machine.\n- SSH access from the control machine to the target VM, with sudo privileges.\n- Git and curl installed on the control machine.\n\nStep-by-step installation:\n1) Clone the repository:\nbash\ngit clone https://github.com/ksamaschke/claude-code-vm.git\ncd claude-code-vm\n\n2) Install prerequisites on the control machine (optional, but recommended):\nbash\nsudo apt-get update\nsudo apt-get install -y software-properties-common python3-venv python3-pip ansible git curl\n\n3) Run the setup to create default configuration files:\nbash\nmake setup\n\n4) Edit configuration files as needed, especially config/.env for credentials and config/mcp-servers.json for MCP server definitions:\nbash\nnano config/.env # add Git tokens and API keys\nnano config/mcp-servers.json # adjust MCP server definitions if necessary\n\n5) Deploy to a target VM (example for Enhanced tier):\nbash\nmake deploy-enhanced VM_HOST=192.168.1.100 TARGET_USER=developer\n\n6) Optional: switch to containerized or Kubernetes-based deployments by selecting the corresponding Make targets:\nbash\nmake deploy-containerized VM_HOST=192.168.1.100 TARGET_USER=developer\nmake deploy-full VM_HOST=192.168.1.100 TARGET_USER=developer\n

Notes and tips:\n- Configuration is driven by config/mcp-servers.json and config/.env. Keep sensitive data out of the project directory when possible by using the External configuration options described in the README.\n- MCP servers may be categorized as requiring API keys (e.g., brave-search, context7, omnisearch) or not. Ensure you provide the necessary API keys via config/.env or the MCP file.\n- The deployment tiers progressively add complexity and tooling. Start with deploy-baseline to validate basic tooling, then scale to enhanced, containerized, and full Kubernetes as needed.\n- If you encounter SSH access issues, ensure the target VM allows SSH from your control machine and that the user has sudo privileges.\n- Environment variables such as KUBERNETES_BACKEND (k3s or kind) and GIT_CONFIG_FILE can be overridden at deploy time.\n- For local testing, the project supports zero-SSH localhost deployments, which can help validate configuration before targeting remote VMs.\n- If MCP servers require API keys, store them securely in config/.env and reference them in MCP configuration using MCP_FILE or env vars as described in the docs.