# Kustomize MCP

An MCP server that helps to refactor [Kubernetes](https://kubernetes.io/)
configuration based on [Kustomize](https://kustomize.io/).

[![asciicast](https://asciinema.org/a/758592.svg)](https://asciinema.org/a/758592)

**Why?** Because Kustomize manifests depend on each other in non-obvious ways,
it's hard for a model to understand how a config change may impact multiple
environments. This MCP server gives them extra tools to make this safer:

* Compute dependencies of a manifest
* Render the end result of Kustomize overlays
* Provide full and summarized diffs between overlays across directories and
  checkpoints.

## Available Tools

- `create_checkpoint`: Creates a checkpoint where rendered configuration will be
  stored.
- `clear_checkpoint`: Clears all checkpoints or a specific checkpoint
- `render`: Renders Kustomize configuration and saves it in a
  checkpoint
- `diff_checkpoints`: Compares all rendered configuration across two checkpoints
- `diff_paths`: Compares two Kustomize configurations rendered in the
  same checkpoint
- `dependencies`: Returns dependencies for a Kustomization file

## Running the Server

> [!NOTE]
> This requires access to your local file system, similarly to how the
> [filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)
> MCP Server works.

### Using Docker

Run the server in a container (using the pre-built image):

```sh
docker run -i --rm -v "$(pwd):/workspace" ghcr.io/mbrt/kustomize-mcp:latest
```

The Docker image includes:
- Python 3.13 with all project dependencies
- kustomize (latest stable)
- helm (latest stable)
- git

Mount your Kustomize configurations to the `/workspace` directory in the
container to work with them.

If you want to rebuild the image from source:

```sh
docker build -t my-kustomize-mcp:latest .
```

And use that image instead of `ghcr.io/mbrt/kustomize-mcp`.

### Using UV (Local Development)

Start the MCP server:

```sh
uv run server.py
```

The server will start by using the STDIO transport.

## Usage with MCP clients

To integrate with VS Code, add the configuration to your user-level MCP
configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP:
Open User Configuration`. This will open your user `mcp.json` file where you can
add the server configuration.

```json
{
  "servers": {
    "kustomize": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/workspace",
        "ghcr.io/mbrt/kustomize-mcp:latest"
      ]
    }
  }
}
```

To integrate with Claude Code, add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kustomize": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-a", "stdin",
        "-a", "stdout",
        "-v", "<PROJECT_DIR>:/workspace",
        "ghcr.io/mbrt/kustomize-mcp:latest"
      ]
    }
  }
}
```

Replace `<PROJECT_DIR>` with the root directory of your project.

To integrate with Gemini CLI, edit `.gemini/settings.json`:

```json
{
  "mcpServers": {
    "kustomize": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-a", "stdin",
        "-a", "stdout",
        "-v", "${PWD}:/workspace",
        "ghcr.io/mbrt/kustomize-mcp:latest"
      ]
    }
  }
}
```

## Testing the Server

Run unit tests:

```sh
pytest
```

After running the server on one shell, use the dev tool to verify the server is
working:

```sh
uv run mcp dev ./server.py
```