<div align="center">

🔖 Git Changelog MCP

MCP server that enables AI agents to read git commits and generate beautiful changelogs

Features • Installation • Usage • Examples • Contributing

</div>

---

🎯 What is this?

Turn your git commits into beautiful, organized changelogs in seconds using AI. This Model Context Protocol (MCP) server gives AI assistants like Claude and Cursor the ability to:

• 📖 Read commit history from any local git repository
• 🎨 Auto-generate formatted changelogs grouped by Features, Fixes, and Chores
• ⚡ Work 100% locally with no API keys required
• 🤖 Integrate seamlessly with any MCP-compatible AI tool

The Problem It Solves

❌ Before: Manually writing changelogs is tedious and time-consuming
❌ Before: Copy-pasting commit messages into release notes
❌ Before: Inconsistent formatting across team members

✅ After: Ask AI "generate a changelog from the last 50 commits"
✅ After: Beautiful, categorized output in seconds
✅ After: Consistent Conventional Commits formatting automatically

---

✨ Features

🛠️ Two Powerful Tools

git_get_recent_commits

Fetch recent commits from a local git repository.

Parameters:

• repoPath (string, required): Absolute or relative path to the git repository
• count (number, optional): Number of commits to fetch (default: 20, max: 500)

Returns: Structured commit objects with hash, date, message, body, author name, and author email.

git_generate_markdown_changelog

Generate a beautifully structured Markdown changelog grouped by Features, Fixes, and Chores.

Parameters:

• commits (array, required): Array of commit objects (typically from git_get_recent_commits)
• title (string, optional): Changelog heading (default: "Changelog")

Returns: Formatted Markdown changelog with commits categorized using Conventional Commits conventions.

🎯 Key Benefits

• ⚡ Lightning Fast - Generate changelogs in seconds
• 🎨 Beautiful Formatting - Automatic grouping by commit type
• 🔒 100% Local - No external APIs, no data leaves your machine
• 🤖 AI-Powered - Works with Claude, Cursor, and any MCP client
• 📝 Conventional Commits - Smart parsing of commit message formats
• 🔧 Flexible - Use for releases, PRs, sprint summaries, or team reports

---

📦 Installation

Option 1: Install via npm (Recommended)

npm install -g git-changelog-mcp

Option 2: Clone and Build

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

---

🚀 Usage

For Cursor IDE

Create or edit .cursor/mcp.json in your workspace:

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

Restart Cursor and the server will be available.

For Claude Desktop

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

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

Restart Claude Desktop to load the server.

If Installed Locally

If you cloned the repo instead of using npm:

{
  "mcpServers": {
    "git-changelog": {
      "command": "node",
      "args": ["/absolute/path/to/git-changelog-mcp/dist/index.js"]
    }
  }
}

---

💡 Examples

Once configured, ask your AI assistant:

Example 1: Simple Changelog

Fetch the last 30 commits from this repository and generate a changelog

Example 2: Release Notes

Get the last 50 commits from C:/projects/my-app and create a changelog 
titled "Release v2.0.0"

Example 3: PR Description

Generate a changelog from the last 10 commits to use as a pull request description

Example 4: Sprint Summary

Show me all commits from the past week formatted as a changelog for our standup

Example Output

## Release v2.0.0

### Features

- Add user authentication with JWT (`a1b2c3d`)
- Implement dark mode toggle (`e4f5g6h`)
- Add pagination to user list (`i7j8k9l`)

### Fixes

- Fix memory leak in WebSocket connection (`m1n2o3p`)
- Resolve CORS issues on API endpoints (`q4r5s6t`)

### Chores

- Update dependencies to latest versions (`u7v8w9x`)
- Refactor database connection pool (`y1z2a3b`)

---

🏗️ Architecture

• Entry point: src/index.ts
• Transport: Stdio (JSON-RPC over stdin/stdout)
• Validation: Zod schemas for type-safe input/output
• Git operations: simple-git library
• Error handling: All diagnostics written to stderr to preserve the JSON-RPC stream

---

🧪 Development

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

# Build and run in one command
npm run dev

---

📋 Requirements

• Node.js 18 or higher
• TypeScript 7+
• A local git repository to inspect

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🔗 Links

• Model Context Protocol Documentation
• MCP Servers Registry
• Conventional Commits
• Report Issues

---

🌟 Show Your Support

If this project helped you, please consider giving it a ⭐ on GitHub!

---

<div align="center">

Made with ❤️ by kslmisel

</div>