MCP Github Notifications

🚀 GitHub Notifications MCP Server

A Model Context Protocol (MCP) server that provides tools for managing GitHub notifications. This server allows AI assistants like Claude to help you manage your GitHub notifications via natural language commands.

🚀 Quick Start

This MCP server offers tools for managing GitHub notifications, enabling AI assistants like Claude to assist you in handling notifications through natural language commands.

✨ Features

• List and filter your GitHub notifications.
• Mark notifications as read.
• View detailed information about notification threads.
• Subscribe to or unsubscribe from notification threads.
• Mark threads as completed.
• Manage notifications for specific repositories.
• Control repository notification settings (all activity, default, or mute).

📦 Installation

Prerequisites

• Node.js 18 or higher.
• A GitHub personal access token (classic) with the notifications or repo scope.

Steps

1. Clone this repository.

   git clone https://github.com/yourusername/github-notifications-mcp-server.git
   cd github-notifications-mcp-server
   

2. Install dependencies.

   npm install
   

3. Build the project.

   npm run build
   

4. Create a .env file containing your GitHub token.

   GITHUB_TOKEN=your_github_personal_access_token_here
   

💻 Usage Examples

Run the server directly

npm start

Use with Claude Desktop

Add the server to the claude_desktop_config.json file:

{
  "mcpServers": {
    "github-notifications": {
      "command": "node",
      "args": ["/absolute/path/to/github-notifications-mcp-server/build/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token_here"
      }
    }
  }
}

Available Tools

Example Prompts

Here are some example prompts you can use with Claude Desktop once the server is successfully connected:

• "Can you check my GitHub notifications?"
• "Show me my unread notifications from the past 24 hours."
• "Mark all notifications as read."
• "Can you tell me about the notification thread numbered 12345?"
• "Unsubscribe from the notification thread numbered 12345."
• "What notifications do I have in the octocat/Hello-World repository?"
• "Mark all notifications in the octocat/Hello-World repository as read."
• "Follow all activity in the octocat/Hello-World repository."
• "Set the octocat/Hello-World repository to the default settings (participation and @ mentions)."
• "Check my notification settings for the octocat/Hello-World repository."
• "Mute the octocat/Hello-World repository."

📚 Documentation

URL Handling

This server automatically converts GitHub API URLs to their corresponding web interface URLs. For example:

• API URL: https://api.github.com/repos/nodejs/node/pulls/57557
• Converted to: https://github.com/nodejs/node/pull/57557

Conversion process:

• Domain conversion from api.github.com/repos to github.com.
• Path correction for pull requests (changing pulls to pull).
• Retention of additional path segments.

Project Structure

github-notifications-mcp-server/
├── src/                    # Source code
│   ├── tools/              # Tool implementations
│   ├── types/              # Type definitions
│   ├── utils/              # Utility functions
│   ├── index.js           # Entry file
│   └── package.json       # File containing dependencies and scripts
└── build/                 # Build output directory, containing executable files

How to Build

Run the following command in the project root directory:

npm run build

This will use webpack to package all modules into build/main.js and provide relevant information upon completion of the build.

📄 License

Please refer to the LICENSE file for the license information of this project.

This is an MCP server for managing GitHub notifications, achieving efficient notification processing through natural language processing and automated scripts.