github-releases-mcp

GitHub Releases MCP Server

A powerful Model Context Protocol (MCP) toolkit for GitHub releases management. This server provides comprehensive tools for accessing, comparing, and analyzing GitHub repository releases with rich formatting and detailed information.

Features

• 🔍 Detailed Release Information: Get comprehensive details about specific releases
• 📊 Version Comparison: Compare changes between any two versions
• 📋 Release Listing: Get formatted lists of releases with filtering options
• 🏷️ Semantic Version Support: Handles various version formats (v1.0.0, @1.0.0, 1.0.0)
• 🎯 Pre-release Filtering: Option to include or exclude pre-releases
• 📝 Rich Formatting: Emoji-enhanced output for better readability
• 🔄 Pagination Support: Handles repositories with many releases
• 🔒 Authentication: Optional GitHub token support for private repositories and extended rate limit

Configuration

The server accepts the following optional environment variables:

• GITHUB_PERSONAL_ACCESS_TOKEN: GitHub Personal Access Token (optional). If provided, it will be used to authenticate API requests, allowing for higher rate limits and access to private repositories.

Quick Start

You can run this MCP server using npx:

# Using environment variables
GITHUB_PERSONAL_ACCESS_TOKEN=your_token npx @slinerodev/github-releases-mcp

# Or using a .env file
echo "GITHUB_PERSONAL_ACCESS_TOKEN=your_token" > .env
npx @slinerodev/github-releases-mcp

Client Configuration

The server can be used with various MCP clients. Add the following configuration to your client's config file:

• Cursor: ~/.cursor/mcp.json
• VS Code: .vscode/settings.json (use mcp.servers instead of mcpServers)
• Claude Desktop: claude_desktop_config.json
• Windsurf: windsurf_config.json

Using Published Version

{
  "mcpServers": {
    "github-releases": {
      "command": "npx",
      "args": [
        "-y",
        "@slinerodev/github-releases-mcp"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Using Local Development Version

{
  "mcpServers": {
    "github-releases": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "${workspaceRoot}/main.ts"
      ]
    }
  }
}

Note:

• For VS Code, replace mcpServers with mcp.servers in the configuration.
• Replace your_token_here with your GitHub Personal Access Token if you want to access private repositories or need higher rate limits.

Available Tools

The server provides three specialized tools for working with GitHub releases:

1. github_release_info

Get detailed information about a specific release version.

const result = await mcp.invoke("github_release_info", {
  owner: "owner-name",
  repo: "repo-name",
  version: "1.0.0" // Supports v1.0.0, @1.0.0, 1.0.0
});

Perfect for:

• Understanding what changed in a specific version
• Documentation purposes
• Release note retrieval

2. github_releases_compare

Compare changes between two versions.

const result = await mcp.invoke("github_releases_compare", {
  owner: "owner-name",
  repo: "repo-name",
  fromVersion: "1.0.0",
  toVersion: "2.0.0"
});

Perfect for:

• Generating changelogs
• Understanding feature evolution
• Migration guides
• Breaking change analysis

3. github_releases_list

List all releases with filtering options.

const result = await mcp.invoke("github_releases_list", {
  owner: "owner-name",
  repo: "repo-name",
  limit: 10, // Optional: limit number of releases
  includePreReleases: false // Optional: include pre-releases
});

Perfect for:

• Project release history overview
• Finding latest versions
• Release frequency monitoring
• Pre-release tracking

Example Response Format

All tools return responses in a consistent, emoji-enhanced format:

🔖 v1.0.0 (First stable release)
🗓️ 2024-03-15T10:30:00Z
📝 This is the release description...

---

🔖 v0.9.0 (Beta) (Pre-release)
🗓️ 2024-03-01T08:15:00Z
📝 Beta version with new features...

Error Handling

The tools handle various error cases gracefully:

• Invalid repository names
• Non-existent versions
• Invalid version formats
• API rate limits
• Network issues
• Authentication errors

Each error returns a clear message explaining what went wrong.

Development

1. Install dependencies:

   pnpm install
   

2. Run the server:

   pnpm start
   

Contributing

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

License

ISC

Author

Sergio Linero