GitHub Notifications MCP Server

Instructions

Implementation Reference

• src/tools/mark-repo-notifications-read.ts:26-70 (handler)

  The main async handler function implementing the tool logic: prepares request body with last_read_at and read flags, calls GitHub API via githubPut to mark repo notifications, handles async response or success/error messages.

  export async function markRepoNotificationsReadHandler(args: z.infer<typeof markRepoNotificationsReadSchema>) {
    try {
      // Prepare request body
      const requestBody = {
        last_read_at: args.last_read_at,
        read: args.read
      };
  
      // Make request to GitHub API
      const response = await githubPut<MarkNotificationsReadResponse>(
        `/repos/${args.owner}/${args.repo}/notifications`, 
        requestBody
      );
  
      // Check if notifications are processed asynchronously
      if (response.message) {
        return {
          content: [{
            type: "text",
            text: `${response.message}`
          }]
        };
      }
  
      // Default success message
      return {
        content: [{
          type: "text",
          text: `Successfully marked notifications for repository ${args.owner}/${args.repo} as ${args.read ? 'read' : 'unread'}.${
            args.last_read_at 
              ? ` Notifications updated on or before ${new Date(args.last_read_at).toLocaleString()} were affected.` 
              : ''
          }`
        }]
      };
    } catch (error) {
      return {
        isError: true,
        content: [{
          type: "text",
          text: formatError(`Failed to mark notifications as read for repository ${args.owner}/${args.repo}`, error)
        }]
      };
    }
  }

• src/tools/mark-repo-notifications-read.ts:12-21 (schema)

  Zod schema defining input parameters: owner, repo (required), last_read_at (optional ISO timestamp), read (optional boolean default true).

  export const markRepoNotificationsReadSchema = z.object({
    owner: z.string().describe("The account owner of the repository"),
    repo: z.string().describe("The name of the repository"),
    last_read_at: z.string().optional().describe(
      "ISO 8601 timestamp - marks notifications updated at or before this time as read. Default is current time."
    ),
    read: z.boolean().optional().default(true).describe(
      "Whether to mark notifications as read or unread"
    )
  });

• src/tools/mark-repo-notifications-read.ts:75-82 (registration)

  Registration function that adds the tool to the MCP server using server.tool() with name, description, schema, and handler.

  export function registerMarkRepoNotificationsReadTool(server: any) {
    server.tool(
      "mark-repo-notifications-read",
      "Mark GitHub notifications for a specific repository as read",
      markRepoNotificationsReadSchema.shape,
      markRepoNotificationsReadHandler
    );
  }

• src/server.ts:47-47 (registration)

  Call to register the mark-repo-notifications-read tool during server initialization in the startServer function.

  registerMarkRepoNotificationsReadTool(server);