renovate-mcp

Requirements

Required

• Linux or macOS. Windows is not supported — package.json declares "os": ["darwin", "linux"], so npm i surfaces an EBADPLATFORM warning on Windows, and the server exits with a clear stderr message at startup. Run on WSL2 or a Linux/macOS host instead.
• Node.js ≥ 24 (aligns with Renovate's own engine requirement).

Renovate ships bundled — the renovate package is a runtime dependency, so validate_config, dry_run, and write_config work out of the box with no separate install. The offline tools (read_config, resolve_config, explain_config, preview_custom_manager, lint_config) never spawn Renovate at all.

Optional

• RENOVATE_BIN / RENOVATE_CONFIG_VALIDATOR_BIN — override the bundled binaries (e.g., to point at a different Renovate install). When set, the override always wins.
• RENOVATE_MCP_REQUIRE_CLI=false — suppress the startup "partial availability" notice when you only intend to use the offline tools.
• Platform env vars — RENOVATE_PLATFORM, RENOVATE_ENDPOINT, and a token (RENOVATE_TOKEN / GITHUB_TOKEN / GITLAB_TOKEN). Needed for dry_run against a remote platform and for resolve_config with externalPresets: true. See Platform setup for the matrix and a worked example.
• Private-registry credentials for dry_run — whatever Renovate itself would need at lookup time (COMPOSER_AUTH, NPM_TOKEN / .npmrc, Docker registry creds, or a RENOVATE_HOST_RULES JSON blob). Alternatively encode these as hostRules in the Renovate config, or pass them per-call via the hostRules input on dry_run (no MCP restart needed). Per-call hostRules are appended to whatever the repo's own config declares. Values reach Renovate as JSON through the tool-call transport, so the calling LLM sees them in its context — prefer the env route if that matters. Without any of these, Renovate's lookup often returns 0 updates silently; dry_run scans its logs for auth failures and surfaces them under problems.

Note: all env vars (tokens, COMPOSER_AUTH, RENOVATE_HOST_RULES, binary overrides, …) must be set on the MCP server process itself — via the env key in claude_desktop_config.json / .mcp.json, not your shell — since the MCP server runs as a child of the client and does not inherit shell env.

Install

npx fetches the published package on demand — no manual install needed. For local development, clone and build first:

npm install
npm run build

Add the following mcpServers entry to your client's config file:

{
  "mcpServers": {
    "renovate": {
      "command": "npx",
      "args": ["-y", "renovate-mcp"]
    }
  }
}

For local development, swap to "command": "node" with "args": ["/absolute/path/to/renovate-mcp/dist/index.js"].

Platform setup

The four common configurations differ in three settings: RENOVATE_PLATFORM, RENOVATE_ENDPOINT, and which token env var you set. Pick the row that matches your environment and put the values in your client's mcpServers.renovate.env block.

Notes that apply to every row:

• All env vars must be on the MCP server process — set them via the env key in .mcp.json / claude_desktop_config.json, not your shell, since the MCP server runs as a child of the client and does not inherit shell env.
• RENOVATE_TOKEN wins when both it and the platform-specific var are set. dry_run and resolve_config honour the same precedence; for dry_run the platform-specific var is auto-translated to RENOVATE_TOKEN for the spawned Renovate CLI (Renovate itself only reads that one var).
• For repository identifiers, GitLab accepts nested-group paths like group/subgroup/project, not just group/project.
• If you only intend to use the offline tools (read_config, resolve_config without externalPresets, preview_custom_manager, lint_config), you can skip all of the above.

Worked example — self-hosted GitLab

{
  "mcpServers": {
    "renovate": {
      "command": "npx",
      "args": ["-y", "renovate-mcp"],
      "env": {
        "RENOVATE_PLATFORM": "gitlab",
        "RENOVATE_ENDPOINT": "https://gitlab.example.com/api/v4/",
        "GITLAB_TOKEN": "<your token>"
      }
    }
  }
}

This is enough for both dry_run (remote-platform runs) and resolve_config (private preset fetches). With this set, dry_run against group/subgroup/project works without passing platform / endpoint / token per call: RENOVATE_PLATFORM and the auto-translated GITLAB_TOKEN cover the platform side, and RENOVATE_ENDPOINT is inherited naturally by the spawned Renovate CLI. For resolve_config, platform and endpoint are tool inputs (not env vars) — pass them when you need local> presets routed through your host, since resolve_config is in-process and doesn't read RENOVATE_* env vars itself.

Example prompts

Once the server is wired up, try prompts like these. They're written for Claude but work with any MCP-capable client.

Understanding an existing config

• "Read the Renovate config in this repo and summarize what it actually does — expand every preset so I can see the real effective behavior."
• "Resolve my config and list anything that landed in presetsUnresolved, with the reason for each."
• "Why is my prCreation set to not-pending? Use explain_config to trace which preset set it."

Browsing presets

• "List the presets in the config namespace." (uses the renovate://presets/config sub-resource — cheaper than pulling the whole index)
• "What does config:recommended actually enable? Show me its expanded JSON."
• "Find a built-in preset that pins GitHub Actions digests."

Self-hosted GitLab / GitHub Enterprise (env set per Platform setup)

• "Resolve my config with external presets enabled, fetching gitlab>platform/renovate-presets from our self-hosted GitLab at https://gitlab.example.com/api/v4. Route local> presets through the same host."
• "Expand github>acme/renovate-config//base from our GitHub Enterprise at https://github.acme.corp/api/v3."
• "Dry-run infrastructure/kubernetes/our-platform (a nested-group GitLab project) so Renovate can fetch the local> presets the config extends."

Authoring a custom manager (regex)

• "I have # renovate: datasource=docker depName=... comments above image tags in my Dockerfiles. Draft a customManagers regex entry and preview it against this repo so I can see what it extracts."
• "Here's a customManagers entry — preview it and tell me which files match, which lines hit each matchStrings regex, and what dep info gets extracted."

Validating, previewing, saving

• "Validate this proposed config against Renovate's schema without writing it anywhere."
• "Do a dry run and show me which PRs Renovate would open — no pushes."
• "Add :semanticCommits to my extends, validate it, and save back to renovate.json."

Example session

A transcript-style walkthrough: design a Dockerfile custom manager from scratch, validate it, dry-run, and save. Turns are abbreviated — your client will show the actual tool-call JSON.

You: I've got # renovate: datasource=docker depName=<image> comments above FROM lines in my Dockerfiles. Draft a customManagers entry and preview it against this repo. Claude calls preview_custom_manager with a first-draft fileMatch + matchStrings. → 4 Dockerfiles matched fileMatch, 0 lines matched matchStrings. The regex anchored on ARG, but the Dockerfiles use FROM. You: Rewrite matchStrings to anchor on the renovate comment, then FROM <image>:<version> on the next line. Claude calls preview_custom_manager again with the fixed regex. → 4 files, 4 line hits. Extracted: postgres:15.3-alpine, redis:7.2, nginx:1.25, node:20.11. Named groups depName and currentValue populated on every hit. You: Good. Validate the full config inline, with this customManagers entry alongside my existing extends. Claude calls validate_config with the inline config. → valid. You: Now dry-run so I can see what Renovate would actually open. Claude calls dry_run. → 2 updates: postgres 15.3-alpine → 15.5-alpine, redis 7.2 → 7.4. No entries in problems. You: Save it. Claude calls write_config on renovate.json. → validated, written atomically.