github-changelog-mcp

An MCP server that turns raw GitHub commit history into a categorized, human-readable changelog — directly inside Claude (or any MCP-compatible client).

You: "Generate a changelog for expressjs/express between v4.18.0 and v4.19.0"

Claude: [calls generate_changelog tool]

## expressjs/express: v4.18.0 → v4.19.0

### Features
- add support for X-Forwarded-Host header (`a1b2c3d`) — @wesleytodd

### Bug Fixes
- prevent ReDoS in query parser (`b2c3d4e`) — @cdoublev

### Chores
- bump path-to-regexp to 0.1.10 (`c3d4e5f`) — @dependabot

No paid APIs. No API keys required to get started (an optional free GitHub token just raises the rate limit).

Why this exists

Writing release notes by hand is tedious and usually done by skimming git log and manually sorting commits into categories. This tool automates that: it fetches the commit diff between two refs via GitHub's public REST API, classifies each commit (Conventional Commits prefix first, keyword heuristics as a fallback), filters out merge-commit noise, and renders clean grouped Markdown — as a tool Claude can call directly in conversation.

Tools

Tool	Description
list_tags	List recent tags for a public repo (use this to find valid ref names)
compare_refs	Raw commit diff between two refs, uncategorized
generate_changelog	The main tool — categorized Markdown changelog between two refs, with optional contributor summary

Setup

git clone https://github.com/SiwarKhalfaoui/github-changelog-mcp.git
cd github-changelog-mcp
npm install
npm run build

Optional — raise the GitHub API rate limit from 60/hr to 5,000/hr:

cp .env.example .env
# add a free token from https://github.com/settings/tokens (no scopes needed)

Connect it to Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "github-changelog": {
      "command": "node",
      "args": ["/absolute/path/to/github-changelog-mcp/build/index.js"],
      "env": {
        "GITHUB_TOKEN": "optional-token-here"
      }
    }
  }
}

Restart Claude Desktop. You should see a 🔨 tools icon confirming the server connected — then just ask Claude to generate a changelog for any public repo.

Development

npm run dev              # run directly with tsx, no build step
npm run test:changelog   # run the categorization logic test suite

Architecture notes

• src/github.ts — thin GitHub REST API wrapper. No SDK dependency, just fetch + a shared header builder. Handles rate-limit errors explicitly and surfaces an actionable message (which token to add, when the limit resets) rather than a raw HTTP error.
• src/changelog.ts — the actual logic: Conventional Commits parsing with a keyword-based fallback for repos that don't use that convention, merge commit filtering, and Markdown rendering.
• src/index.ts — MCP server wiring (tool registration, schemas via zod, stdio transport).

Kept intentionally dependency-light — GitHub's REST API and MCP's official SDK are the only two runtime dependencies. No frameworks, no ORMs, no unnecessary abstraction for a tool this size.

Possible extensions

• Group changelog entries by scope (feat(auth): ... → group under "Auth") in addition to type
• Compare against unreleased commits (to_ref = default branch) and suggest the next semver bump based on commit types present
• Cache compareRefs responses per (owner, repo, base, head) to reduce API calls on repeated queries in the same session

License

MIT