Skip to content
GitLab MCP Server GitLab MCP Server GitLab MCP Server

Auto-update

GitLab MCP Server can automatically detect, download, and apply new releases from GitHub. Updates use a rename trick — the running binary is renamed to .old and the new binary is placed at the original path. The running MCP process keeps serving; restart it to use the new binary.

Update modes

Section titled “Update modes”

The AUTO_UPDATE variable controls how updates are handled:

| Value | Mode | Behavior | | ---------------- | ----------- | ----------------------------------------------------- | | true (default) | Auto-apply | Detect and apply updates automatically | | check | Notify only | Detect updates and log availability, but do not apply | | false | Disabled | Skip all update checks entirely |

Accepted aliases: 1/yes for true, 0/no for false. The value is case-insensitive.

How it works

Section titled “How it works”
sequenceDiagram
    participant Server as gitlab-mcp-server
    participant Update as Background update goroutine
    participant GitHub as GitHub Releases API
    participant FS as File System

    Server->>Server: CleanupOldBinary()
    Server->>Update: Start startup check in background
    Server->>Server: Continue MCP startup immediately
    Update->>GitHub: GET /repos/:owner/:repo/releases/latest
    GitHub-->>Update: Release metadata + asset URLs
    alt Update available
        Update->>GitHub: Download binary asset
        Update->>FS: Write to .tmp staging file
        Update->>FS: Rename current → .old
        Update->>FS: Rename .tmp → current path
        Update->>Server: Log restart advisory
    else Up to date
        Update->>Server: Log "server is up to date"
    end

Startup check (stdio mode)

Section titled “Startup check (stdio mode)”

In stdio mode (the default), auto-update runs as a background startup check with a configurable timeout (default: 60 seconds). MCP startup continues immediately while release detection and downloads run in the background:

  1. CleanupOldBinary() removes any leftover .old file from a previous update
  2. The server schedules the update check in a background goroutine
  3. Checks for a newer release on GitHub without blocking MCP tool negotiation
  4. If mode is true and a newer version exists, downloads and replaces the binary
  5. Logs a restart advisory so the next server process uses the new version

The startup check is non-blocking and non-fatal — any error (network timeout, missing releases) is logged as a warning and does not prevent the server from starting or accepting MCP requests.

Periodic check (HTTP mode)

Section titled “Periodic check (HTTP mode)”

In HTTP mode, auto-update runs as a background periodic check:

  1. A goroutine checks for updates every AUTO_UPDATE_INTERVAL (default: 1 hour)
  2. Each cycle checks GitHub for a newer release with a 30-second timeout
  3. If mode is true, applies the update and logs a restart advisory
  4. The goroutine stops when the server shuts down

Configuration

Section titled “Configuration”

Environment variables (stdio mode)

Section titled “Environment variables (stdio mode)”

| Variable | Default | Description | | ---------------------- | ---------------------------- | -------------------------------------------------------- | | AUTO_UPDATE | true | Update mode: true, check, or false | | AUTO_UPDATE_REPO | jmrplens/gitlab-mcp-server | GitHub repository slug (owner/repo) for release assets | | AUTO_UPDATE_INTERVAL | 1h | Check interval (used by HTTP mode periodic checks) | | AUTO_UPDATE_TIMEOUT | 60s | Startup/background update timeout (range: 5s–10m) |

CLI flags (HTTP mode)

Section titled “CLI flags (HTTP mode)”

| Flag | Default | Description | | ------------------------ | ---------------------------- | -------------------------------------------------------- | | --auto-update | true | Update mode: true, check, or false | | --auto-update-repo | jmrplens/gitlab-mcp-server | GitHub repository slug (owner/repo) for release assets | | --auto-update-interval | 1h | Interval between periodic update checks | | --auto-update-timeout | 60s | Startup/background update timeout (range: 5s–10m) |

Configuration examples

Section titled “Configuration examples”

Disable auto-update entirely:

AUTO_UPDATE=false

Check-only mode (log availability but do not apply):

AUTO_UPDATE=check

Use a custom fork repository:

AUTO_UPDATE_REPO=my-org/my-gitlab-mcp-fork

Shutdown flag for external updaters

Section titled “Shutdown flag for external updaters”

External tools (such as pe-agnostic-store) can terminate all running instances before replacing the binary on disk:

Terminal window
gitlab-mcp-server --shutdown

This flag:

  1. Finds all running gitlab-mcp-server processes by name
  2. Sends a graceful termination signal
  3. Waits up to 5 seconds for processes to exit
  4. Force-kills any remaining processes
  5. Exits — no MCP server is started

No admin or root permissions are required. This works on Linux, macOS, and Windows.

Rollback

Section titled “Rollback”

If an update causes issues:

  1. The previous binary is preserved as gitlab-mcp-server.old (or .exe.old on Windows) next to the current binary
  2. To rollback, stop the server and rename the .old file back to the original name
  3. The .old file is automatically cleaned up on the next successful startup

Custom repository support

Section titled “Custom repository support”

You can point auto-update at any GitHub repository that follows the expected release format:

  1. Set AUTO_UPDATE_REPO=owner/repo to your repository
  2. Create GitHub releases with platform binaries named gitlab-mcp-server-{os}-{arch}
  3. Include a checksums.txt asset with SHA-256 hashes (goreleaser format)