# list_notifications

Lists all GitHub notifications for the authenticated user, including unread notifications, mentions, review requests, assignments, and updates on issues or pull requests. Use this tool whenever the user asks what to work on next, requests a summary of their GitHub activity, wants to see pending reviews, or needs to check for new updates or tasks. This tool is the primary way to discover actionable items, reminders, and outstanding work on GitHub. Always call this tool when asked what to work on next, what is pending, or what needs attention in GitHub.

Agent View of the PolicyLayer registry record for `list_notifications`. HTML page: https://policylayer.com/tools/github/list-notifications

## Facts

- Tool: `list_notifications`
- Server: GitHub (`oci:ghcr.io/github/github-mcp-server:1.3.0`) — https://policylayer.com/tools/github.md
- Homepage: https://github.com/github/github-mcp-server
- Risk category: Read (Low risk)
- Registry record: grade D, identity verified
- Server auth posture: gated
- Server rate-limited: no
- Parameters: 7
- Recommended policy verdict: Allowed

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | number | no | Page number for pagination (min 1) |
| `repo` | string | no | Optional repository name. If provided with owner, only notifications for this repository are listed. |
| `owner` | string | no | Optional repository owner. If provided with repo, only notifications for this repository are listed. |
| `since` | string | no | Only show notifications updated after the given time (ISO 8601 format) |
| `before` | string | no | Only show notifications updated before the given time (ISO 8601 format) |
| `filter` | string | no | Filter notifications to, use default unless specified. Read notifications are ones that have already been acknowledged by the user. Participating notifications |
| `perPage` | number | no | Results per page for pagination (min 1, max 100) |

Parameters from the server's own tool schema.

## Example call (MCP tools/call, JSON-RPC 2.0)

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_notifications",
    "arguments": {}
  }
}
```

## Why list_notifications is rated Low

This tool queries and retrieves existing notification data for the authenticated user without creating, modifying, deleting, or executing any operations. It is purely informational and produces no side effects, making it a Read category tool with low severity. The blast radius is minimal—misuse would only expose information the user already has access to.

From the tool's own definition: "Tool description states it 'Lists all GitHub notifications' and 'retrieves' unread notifications, mentions, review requests, assignments, and updates."

## Use case

AI agents call list_notifications to retrieve information from GitHub without modifying anything. It is typically the context-gathering step in research, monitoring, and reporting workflows, before the agent takes action elsewhere.

## Recommended policy (PolicyLayer)

Verdict: **Allowed**. Enforced by the PolicyLayer MCP gateway (https://policylayer.com/mcp-gateway) before a call reaches GitHub:

```json
{
  "version": "1",
  "default": "deny",
  "tools": {
    "list_notifications": {}
  }
}
```

## Other tools on GitHub (85)

- `delete_file` — Destructive — https://policylayer.com/tools/github/delete-file.md
- `projects_write` — Destructive — https://policylayer.com/tools/github/projects-write.md
- `actions_run_trigger` — Execute — https://policylayer.com/tools/github/actions-run-trigger.md
- `assign_copilot_to_issue` — Execute — https://policylayer.com/tools/github/assign-copilot-to-issue.md
- `actions_get` — Read — https://policylayer.com/tools/github/actions-get.md
- `actions_list` — Read — https://policylayer.com/tools/github/actions-list.md
- `get_code_scanning_alert` — Read — https://policylayer.com/tools/github/get-code-scanning-alert.md
- `get_commit` — Read — https://policylayer.com/tools/github/get-commit.md
- `get_copilot_job_status` — Read — https://policylayer.com/tools/github/get-copilot-job-status.md
- `get_copilot_space` — Read — https://policylayer.com/tools/github/get-copilot-space.md
- `get_dependabot_alert` — Read — https://policylayer.com/tools/github/get-dependabot-alert.md
- `get_discussion` — Read — https://policylayer.com/tools/github/get-discussion.md
- `get_discussion_comments` — Read — https://policylayer.com/tools/github/get-discussion-comments.md
- `get_file_contents` — Read — https://policylayer.com/tools/github/get-file-contents.md
- `get_gist` — Read — https://policylayer.com/tools/github/get-gist.md
- `get_global_security_advisory` — Read — https://policylayer.com/tools/github/get-global-security-advisory.md
- `get_job_logs` — Read — https://policylayer.com/tools/github/get-job-logs.md
- `get_label` — Read — https://policylayer.com/tools/github/get-label.md
- `get_latest_release` — Read — https://policylayer.com/tools/github/get-latest-release.md
- `get_me` — Read — https://policylayer.com/tools/github/get-me.md
- `get_notification_details` — Read — https://policylayer.com/tools/github/get-notification-details.md
- `get_release_by_tag` — Read — https://policylayer.com/tools/github/get-release-by-tag.md
- `get_repository_tree` — Read — https://policylayer.com/tools/github/get-repository-tree.md
- `get_secret_scanning_alert` — Read — https://policylayer.com/tools/github/get-secret-scanning-alert.md
- `get_tag` — Read — https://policylayer.com/tools/github/get-tag.md
- `get_team_members` — Read — https://policylayer.com/tools/github/get-team-members.md
- `get_teams` — Read — https://policylayer.com/tools/github/get-teams.md
- `github_support_docs_search` — Read — https://policylayer.com/tools/github/github-support-docs-search.md
- `issue_read` — Read — https://policylayer.com/tools/github/issue-read.md
- `list_branches` — Read — https://policylayer.com/tools/github/list-branches.md
- …and 55 more: https://policylayer.com/tools/github.md

## For agents

This record is a snapshot. Live verdicts and the full registry:

- Check every server in your MCP config at once: `npx -y policylayer stack`
- Vet a server before you add it: install the mcp-precheck skill — `npx skills add https://policylayer.com` (skill text: https://policylayer.com/skill.md)
- Query the registry over MCP: endpoint `https://api.policylayer.com/mcp` — tools `check_mcp_server`, `check_mcp_stack`, `check_tool`, `search_registry`, `get_change_events`

---

Source: the PolicyLayer MCP registry — one continuously verified record per MCP server. Full record: https://policylayer.com/registry?q=github · API: https://policylayer.com/registry/api · Policy library: https://policylayer.com/policies/github