MCP Progress Server

An MCP (Model Context Protocol) server that provides notifications and progress tracking for long-running operations.

Features

• Notifications: Display system notifications using node-notifier
• Progress Tracking: Track progress of long-running operations with MCP-compatible progress notifications

Installation

For use with npx (recommended)

npx mcp-progress

For global installation

npm install -g mcp-progress

For local development

git clone git@github.com:jaume-ferrarons/mcp-progress.git
cd mcp-progress
npm install

Usage

Run the server:

npm start

Or use it as an MCP server in your MCP client configuration.

Tools

notify

Display a notification to the user.

Parameters:

• title (string, required): Notification title
• message (string, required): Notification message
• sound (boolean, optional): Play notification sound (default: false)

Note: Notifications stay visible until dismissed by the user.

Example:

{
  "title": "Task Complete",
  "message": "Your operation finished successfully",
  "sound": true
}

start_progress

Start tracking progress for a long-running operation. Creates a sticky notification that updates as progress changes.

Parameters:

• progressToken (string, required): Unique identifier for this progress operation
• title (string, required): Title of the operation
• total (number, optional): Total number of steps

Example:

{
  "progressToken": "file-processing-1",
  "title": "Processing files",
  "total": 100
}

update_progress

Update progress for an ongoing operation. Updates the sticky notification with current progress.

Parameters:

• progressToken (string, required): Progress operation identifier
• current (number, required): Current progress value
• total (number, optional): Total progress value (updates total if provided)
• message (string, optional): Progress message

Example:

{
  "progressToken": "file-processing-1",
  "current": 45,
  "message": "Processing file 45 of 100"
}

complete_progress

Mark a progress operation as complete. Updates the notification with completion status and plays a sound.

Parameters:

• progressToken (string, required): Progress operation identifier
• message (string, optional): Completion message

Example:

{
  "progressToken": "file-processing-1",
  "message": "All files processed successfully"
}

Example Workflow

// Start progress tracking
await callTool('start_progress', {
  progressToken: 'data-sync-1',
  title: 'Syncing data',
  total: 50
});

// Update progress periodically
for (let i = 1; i <= 50; i++) {
  await callTool('update_progress', {
    progressToken: 'data-sync-1',
    current: i,
    message: `Processing item ${i}`
  });
}

// Complete the operation
await callTool('complete_progress', {
  progressToken: 'data-sync-1',
  message: 'Sync completed'
});

// Send a notification
await callTool('notify', {
  title: 'Sync Complete',
  message: 'Data synchronization finished successfully',
  sound: true
});

MCP Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "progress": {
      "command": "npx",
      "args": ["-y", "mcp-progress"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "progress": {
      "command": "mcp-progress"
    }
  }
}

License

ISC

VS Code Setup

This project is configured to work with GitHub Copilot in VS Code. The MCP server configuration is in .vscode/mcp.json.

To use with Copilot:

1. Open this project in VS Code
2. Make sure GitHub Copilot Chat is enabled
3. The MCP server will be automatically available in Copilot Chat
4. Use the tools: @workspace /tools to see available tools

You can also configure it globally by adding to your VS Code settings:

{
  "github.copilot.chat.mcp.enabled": true
}