Release Notes MCP

release-notes-mcp

A small, generic MCP server that combines GitHub releases from several repositories into a single product release note. The server just fetches and bundles raw data; the LLM synthesizes the final notes.

Nothing is architecture-specific:

• `provider` — which forge to read releases from: github (default), gitlab, or gitea/Forgejo. Release fetching goes through a small adapter, so adding a forge means normalizing its release JSON — a contained change.
• `repos` — the repos the server is allowed to read releases from.
• `contextSources` — arbitrary URLs loaded as background context (a style guide, a versions file, feature names — anything). The server assigns no meaning; what each source *is* is decided by what you put behind the URL.

Configuration

Config holds no secrets — only the repo set and context. Provider and auth come from the environment.

// config.json — non-sensitive (required; the server errors if it's missing)

{ "repos": [ "myorg/auth-service", "myorg/web" ], "contextSources": [ { "name": "release-info", "url": "https://example.github.io/whatever/release.json", "description": "Extra context to consult when assembling release notes" } ] }

Environment (provider-agnostic, set in .env or your shell):

• format on a context source is optional — auto-detected from Content-Type / URL extension / content sniffing. Override only when wrong.

Token permissions

The server only ever reads releases (GET /repos/{owner}/{repo}/releases…), so give TOKEN the minimum read scope — never write access.

For GitHub, a fine-grained PAT scoped to just the repos in config.json with Contents → Read-only is the tightest setup and is all this server requires.

The config (repos + contextSources) must come from one of two places — the server errors on startup if neither is set:

Inline JSON wins when both are set. Copy config.example.json to get started with the file approach.

Tools

Selection is dynamic — you (or Claude) pass the (repo, tag) pairs to combine. The server's instructions tell Claude to call get_context() first.

Run

The server runs in a container over HTTP transport on localhost:8000. First create the config and env files (both runs need them):

cp config.example.json config.json   # edit repos + contextSources (no secrets)

cp .env.example .env # set TOKEN (+ PROVIDER / BASE_URL if needed)

Normal run

docker compose up -d

Local development — docker compose watch

For local dev, docker compose watch keeps the server live while you edit:

docker compose watch

Run with uvx (no clone, no container)

The server is published to PyPI, so a client can launch it on demand with uvx — no checkout and no Docker:

uvx release-notes-mcp

uvx talks to the server over stdio (the default transport). Since there's no file to mount, pass the config inline as JSON via RELEASE_MCP_CONFIG_JSON (everything is env-only — ideal for MCP hubs):

RELEASE_MCP_CONFIG_JSON='{"repos":["myorg/web"],"contextSources":[]}' \

TOKEN=ghp_... uvx release-notes-mcp

Prefer a file? Point RELEASE_MCP_CONFIG at an absolute path instead (uvx runs from an unknown working directory, so a relative path won't resolve):

RELEASE_MCP_CONFIG=/abs/path/config.json TOKEN=ghp_... uvx release-notes-mcp

Register with Claude Code

HTTP (container) — point Claude Code at the running server by its URL:

claude mcp add --transport http release-notes http://localhost:8000/mcp

stdio (`uvx`) — let Claude Code launch the server as a subprocess:

claude mcp add release-notes \

--env RELEASE_MCP_CONFIG=/abs/path/config.json \ --env TOKEN=ghp_... \ -- uvx release-notes-mcp

Then ask Claude: *"Combine the latest releases of auth-service and web into a product release note."*