https://github.com/mcollina/mcp-github-notifications
An MCP server for the github notifications API for the OSS maintainer
https://github.com/mcollina/mcp-github-notifications
Last synced: about 1 month ago
JSON representation
An MCP server for the github notifications API for the OSS maintainer
- Host: GitHub
- URL: https://github.com/mcollina/mcp-github-notifications
- Owner: mcollina
- License: mit
- Created: 2025-03-21T08:21:56.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-03-31T08:15:36.000Z (3 months ago)
- Last Synced: 2025-04-30T18:15:47.819Z (about 2 months ago)
- Language: TypeScript
- Size: 32.2 KB
- Stars: 13
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- mcp-index - GitHub Notifications Server - Manage GitHub notifications with natural language commands, enabling users to list, read, and organize notifications efficiently. Control repository-specific settings and automate notification management to streamline workflows. (APIs and HTTP Requests)
README
# GitHub Notifications MCP Server
An MCP (Model Context Protocol) server that provides tools for managing GitHub notifications. This server allows AI assistants like Claude to help you manage your GitHub notifications through natural language commands.
## Features
- List and filter your GitHub notifications
- Mark notifications as read
- View notification thread details
- Subscribe or unsubscribe from notification threads
- Mark threads as done
- Manage repository-specific notifications
- Control repository notification settings (all activity, default, or mute)
## Prerequisites
- Node.js 18 or higher
- GitHub Personal Access Token (classic) with `notifications` or `repo` scope
## Installation
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 with your GitHub token
```
GITHUB_TOKEN=your_github_personal_access_token_here
```
## Usage
### Running the server directly
```
npm start
```
### Using with Claude Desktop
Add the server to your `claude_desktop_config.json` file:
```json
{
"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
| Tool Name | Description |
|-----------|-------------|
| `list-notifications` | List all GitHub notifications for the authenticated user |
| `mark-notifications-read` | Mark all notifications as read |
| `get-thread` | Get information about a notification thread |
| `mark-thread-read` | Mark a specific thread as read |
| `mark-thread-done` | Mark a thread as done |
| `get-thread-subscription` | Get subscription status for a thread |
| `set-thread-subscription` | Subscribe to a thread |
| `delete-thread-subscription` | Unsubscribe from a thread |
| `list-repo-notifications` | List notifications for a specific repository |
| `mark-repo-notifications-read` | Mark notifications for a repository as read |
| `manage-repo-subscription` | Manage repository subscriptions: all_activity, default (participating and @mentions), or ignore (mute) |
## Example Prompts
Here are some example prompts you can use with Claude Desktop once the server is connected:
- "Can you check my GitHub notifications?"
- "Show me my unread notifications from the last 24 hours."
- "Mark all my notifications as read."
- "Can you tell me about notification thread 12345?"
- "Unsubscribe me from thread 12345."
- "What notifications do I have for the octocat/Hello-World repository?"
- "Mark all notifications from the octocat/Hello-World repository as read."
- "Watch all activity on the octocat/Hello-World repository."
- "Set the octocat/Hello-World repository to default settings (participating and @mentions)."
- "Check my notification settings for the octocat/Hello-World repository."
- "Mute all notifications from the octocat/Hello-World repository."
## Development
### URL Handling
This server automatically converts GitHub API URLs to their corresponding web UI URLs. For example:
- API URL: `https://api.github.com/repos/nodejs/node/pulls/57557`
- Converted to: `https://github.com/nodejs/node/pull/57557`
The conversion handles:
- Domain conversion from `api.github.com/repos` to `github.com`
- Path correction for pull requests (changing `pulls` to `pull`)
- Preservation of additional path segments
### Project Structure
```
github-notifications-mcp-server/
├── src/ # Source code
│ ├── tools/ # Tool implementations
│ ├── types/ # Type definitions
│ ├── utils/ # Utility functions
│ ├── index.ts # Entry point
│ └── server.ts # Server configuration
├── build/ # Compiled JavaScript
├── .env # Environment variables
├── package.json # Dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # Documentation
```
### Building
```
npm run build
```
### Testing
Run the automated tests:
```
npm test
```
Test URL conversion manually:
```
npm run test:url
```
## License
MIT