renovate-mcp

An MCP server for designing Renovate configurations interactively. Point it at a local repo and let an LLM help you read, validate, preview, and save renovate.json.

Quick start

curl -fsSL https://raw.githubusercontent.com/tibuntu/renovate-mcp/main/install.sh | bash

Or add this entry manually to your client's mcpServers config:

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

Restart your client and try the prompt: "List the namespaces available under renovate://presets." A response listing config, docker, npm, … confirms the server is reachable. Long-form install options are under Install below.

What you can do

• Read and explain configs — locate the active renovate.json*, expand every extends preset offline, and trace which preset set each field.

• Discover presets from intent — describe what you want ("automerge patches, group dev deps") and get ranked built-in (and your own local-repo) presets, plus a draft config skeleton when nothing fits.

• Preview custom managers before running Renovate — regex and JSONata, with file/line hits and extracted dep info.

• Validate and lint — schema validation plus a semantic lint pass for Renovate-specific footguns (unwrapped regexes, unknown manager names, deprecated keys).

• Dry-run against a local checkout or a remote GitHub/GitLab — see exactly which PRs Renovate would open.

• Save back atomically — round-trip writes preserve comments and key order in existing JSON-with-comments files.

Tools & resources

Seventeen tools, six resources, and three workflow prompts. Each tool name below links to its full reference in docs/tools.md.

Prompts. Three workflow prompts package the tool sequences above into ready-to-run starting points. Claude Code surfaces MCP prompts as slash commands (e.g. /mcp__renovate__design-renovate-config); other MCP clients expose them through their own prompt picker.

Requirements

• 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. Use 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, suggest_presets, resolve_config, explain_config, resolve_config_diff, preview_custom_manager, lint_config, explain_dependency) never spawn Renovate at all.

Optional env vars:

• RENOVATE_BIN / RENOVATE_CONFIG_VALIDATOR_BIN — override the bundled binaries. 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 + token env vars — see docs/platform-setup.md for the per-platform matrix.

• GITHUB_COM_TOKEN — authenticates github.com datasource lookups (release notes, github-tags / github-releases / github-actions). Distinct from the platform token and never auto-derived from it; set it when github.com-hosted deps are resolved under the default dry_run platform: local. See docs/security.md.

Heads up: MCP servers do not inherit your shell env. Set every env var via the env key in .mcp.json / claude_desktop_config.json. See docs/security.md.

Install

Quick install

curl -fsSL https://raw.githubusercontent.com/tibuntu/renovate-mcp/main/install.sh | bash

The script checks Node ≥ 24, asks whether you want npx-on-demand or a global install, runs an MCP initialize handshake to verify the binary works, and — when the Claude Code CLI is on PATH — auto-registers renovate in user scope via claude mcp add. Useful flags (pass after bash -s --): --global, --npx, --no-mcp-add, --mcp-scope=user|project|local, --version=X.Y.Z. The same flags are also accepted as env vars (RENOVATE_MCP_GLOBAL=1, RENOVATE_MCP_NO_MCP_ADD=1, RENOVATE_MCP_VERSION=…).

Manual install

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

npm install
npm run build

Client config locations

• Claude Code — .mcp.json (project) or ~/.claude.json (user).

• Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json.

• Other MCP clients — any client that can launch a stdio MCP server works; point it at the same npx -y renovate-mcp command.

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

Platform setup

For dry_run against a remote platform or resolve_config with externalPresets: true:

See docs/platform-setup.md for a worked self-hosted GitLab example, local> preset handling, and private-registry credentials.

Example prompts

Once the server is wired up, try prompts like these. 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."

Discovering & browsing presets

• "I want to automerge patch and minor updates and group my dev dependencies — suggest presets for that, search my ../renovate-presets repo too, and draft a config I can validate."

• "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." (or use suggest_presets with that intent)

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 or JSONata)

• "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."

• "Draft a customType: \"jsonata\" customManager with fileFormat: \"yaml\" to extract Helm chart dependencies (name, version, repository) from Chart.yaml, and preview it against this repo."

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."

• "Why didn't Renovate update lodash? Run a dry run and explain that dependency."

• "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; because the file already existed and parsed as JSON-with-comments, the round-trip serializer preserved the surrounding comments and key order — only the customManagers slice was edited in place.

Development

npm run dev                     # build watch mode
npm run typecheck               # tsc --noEmit
npm run build                   # compile to dist/
npm start                       # run the built server over stdio
npm test                        # vitest run (builds first)
npm run test:watch              # vitest watch mode
npm run test:coverage           # vitest run --coverage
npm run generate:presets        # regenerate src/data/presets.generated.ts
npm run generate:managers       # regenerate src/data/managers.generated.ts
npm run generate:migrations     # regenerate src/data/migrations.generated.ts
npm run generate:options        # regenerate src/data/options.generated.ts
npm run check:snapshot-versions # fail if any src/data/*.generated.ts is stale vs installed renovate

See docs/development.md for snapshot-file mechanics, CI matrix, the nightly upstream-drift workflow, dependency review, and integration-test setup.

Further reading

• docs/tools.md — full per-tool reference with all inputs, outputs, and edge cases.

• docs/platform-setup.md — per-platform env vars, worked example, local> presets, private-registry credentials.

• docs/security.md — token handling, env-var precedence, endpoint allowlist, redirect/body-cap policy, inline-secrets warning.

• docs/operations.md — timeouts, caps, large-report escape hatch, ok semantics, RE2 / nodeEnv handling, progress notifications.

• docs/architecture.md — shell-out vs import, worker isolation, round-trip writer, preset catalogue.

• docs/development.md — snapshot mechanics, CI matrix, nightly drift workflow, integration testing.

What this is NOT

• Not a Renovate replacement. This server doesn't open PRs, run scheduled updates, or execute in CI — it's a design-time companion for a local renovate.json. Use the real Renovate for the actual dependency-update pipeline.

• resolve_config merges faithfully. Preset expansion runs offline against a committed snapshot, then folds with Renovate's real mergeChildConfig in a worker thread — mergeQuality: "faithful" (it falls back to an approximate in-process merge as "preview" only if the worker is unavailable). Template substitution still implements only positional {{argN}} placeholders — non-positional tokens and Handlebars helpers are flagged in warnings and pass through verbatim. For full config resolution (datasource lookups, etc.), run dry_run.

• preview_custom_manager is a subset of Renovate's custom managers. It covers customType: "regex" (with matchStringsStrategy of any / combination / recursive) and customType: "jsonata" (with fileFormat: "json" | "yaml" | "toml"). Template substitution is {{groupName}} only — full Handlebars helpers/conditionals are not implemented. Other custom types (e.g. html) are out of scope. Use it for fast iteration; confirm with dry_run. Full coverage matrix in docs/tools.md#preview_custom_manager.

• validate_config / dry_run aren't exercised end-to-end in CI. The bundled Renovate is available (it's a runtime dep), but the integration tests use fake binaries via RENOVATE_BIN / RENOVATE_CONFIG_VALIDATOR_BIN env overrides for determinism and speed. Run the tools locally against a real config to validate behaviour.