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):

Var	Purpose	Default
`TOKEN`	Auth token for the provider — never in config	(empty; ok for public repos)
`PROVIDER`	`github` \| `gitlab` \| `gitea` (overrides config)	`github`
`BASE_URL`	API base — only for self-hosted GitLab / Gitea	provider default

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.

Provider	Public repos	Private repos
GitHub — fine-grained PAT	no token needed	Contents: Read-only (releases live under Contents), for each repo you list
GitHub — classic PAT	no token needed (or `public_repo`)	`repo` scope
GitLab	no token needed	`read_api` scope
Gitea / Forgejo	no token needed	`read:repository` scope

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:

Source	Use it for
`RELEASE_MCP_CONFIG_JSON`	The config as inline JSON. No file needed — ideal for `uvx` / MCP hubs where everything is an env var.
`RELEASE_MCP_CONFIG`	Path to a `config.json` file (default `./config.json`). Used by the container, which mounts a real file.

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

Tools

Tool	Purpose
`list_repos()`	The configured repos
`list_releases(repo, limit)`	Recent releases for one repo
`get_latest_version(repo)`	Newest release for one repo
`get_release(repo, tag)`	Full notes for one tag
`compare_releases(repo, from_tag, to_tag)`	All releases between two versions
`gather_release_notes(selections[])`	Bundle raw notes from N `(repo, tag)` pairs (concurrent)
`get_context(name?)`	Load configured context URLs (auto-detected format)

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

Change	Action
`server.py`	sync + restart — copied into the container, process restarts
`requirements.txt`, `Dockerfile`	rebuild — image is rebuilt automatically
`config.json`	bind-mounted (live); run `docker compose restart` to reload it

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