What is Notify Mcp

Notify MCP is a Model Context Protocol (MCP) server that provides desktop notification functionality, allowing MCP clients to send custom desktop notifications with titles and messages.

Use cases

Use cases include notifying users of task completions, alerts from automated scripts, and integration with applications that require real-time user feedback.

How to use

To use notify-mcp, clone the repository, build the application using Rust, and run it natively or via Docker for better isolation and portability. The server will listen for notifications on a specified port.

Key features

Key features include compliance with MCP standards, a simple API for sending notifications, integration with native OS notification systems, Docker support with customizable UID/GID, and a minimal Docker image.

Where to use

Notify MCP can be used in environments where desktop notifications are needed, such as development environments, automated task notifications, or any application that requires user alerts.

Notify MCP Server 🔔

A Model Context Protocol (MCP) server that provides desktop notification functionality. This server exposes a tool that can be used by MCP clients to send desktop notifications with custom titles and messages.

This is an exploration into mcp usage and will not be of use if you run this server locally and connect it to a client that can then notify you when it is done with a task.

Features ✨

• MCP-compliant server with SSE transport.
• Simple API for sending desktop notifications.
• Integrates with native OS notification systems.
• Docker support with runtime UID/GID configuration and D-Bus passthrough for notifications from container.
• Minimal Docker image using FROM scratch.

Getting Started 🚀

Prerequisites

• Rust toolchain (1.76.0 or later).
• A system that supports desktop notifications (Linux/macOS/Windows for local runs).
• Docker (if using the containerized version).

Installation & Running

1. Clone the Repository:

git clone https://github.com/Tuurlijk/notify-mcp.git
cd notify-mcp

2. Running Natively:

cargo build --release
cargo run --release

The server will start (by default on http://127.0.0.1:3000).

3. Building and Running with Docker (Recommended for Isolation & Portability):

First, build the Docker image:

./build.sh

This script will:

• Compile the Rust application for x86_64-unknown-linux-musl (for a static binary).
• Build a Docker image named michielroos/notify-mcp using a FROM scratch base.

Then, run the container using the run.sh script:

./run.sh

This script will:

• Stop and remove any existing container named notify-mcp-container.
• Start a new Docker container from the michielroos/notify-mcp image.
• The server inside the container will listen on the port specified by the PORT environment variable (defaults to 3000), mapped to the same port on your host.

Docker: Custom UID/GID and D-Bus for Notifications (via run.sh)

• Runtime UID/GID: The run.sh script allows you to run the application inside the Docker container with a specific UID and GID. By default, it uses your current host user’s UID/GID (if detectable via id -u/id -g) or falls back to 1000. You can customize this by setting APP_UID and APP_GID environment variables before running run.sh:

  APP_UID=1001 APP_GID=1001 ./run.sh
  

• D-Bus for Desktop Notifications from Container: For the containerized server to send desktop notifications to your host system, the run.sh script mounts your host’s D-Bus socket (typically $XDG_RUNTIME_DIR/bus) into the container. It also sets the necessary environment variables (DBUS_SESSION_BUS_ADDRESS, XDG_RUNTIME_DIR) inside the container for the application to find and use this socket. This allows notify-rust (and underlying libraries) to communicate with your host’s notification daemon.
  • Security Note: Mounting the D-Bus socket reduces container isolation. While necessary for this feature, be aware that a compromised container could potentially interact with other D-Bus services on your host. Use with caution, especially if the container image source is not fully trusted or in multi-user environments.

Usage 📋

This server can be used with any MCP client that supports SSE transport, such as:

• GitHub Copilot in VS Code
• Claude desktop app (if it supports custom MCP SSE servers)
• Custom MCP clients

Adding the Server to VS Code

1. Open VS Code (with GitHub Copilot or a similar MCP-enabled extension).
2. Run the command: MCP: Add server (or the equivalent for your extension).
3. Choose “HTTP (Server-sent events)” as the transport.
4. Enter the server URL. If running locally (native or Docker via build.sh default): http://127.0.0.1:3000/sse (or your custom port if PORT env var was set).
5. Start the server from the MCP panel in VS Code.

Example Usage

Once connected, you can instruct your MCP client to use the notify tool:

@mcp notify title="Hello from MCP" message="This notification came via the server!"

Or in a more conversational way with an agent:

Send a notification with the title "Reminder" and the message "Meeting in 5 minutes."

Available Tools 🛠️

Notify Tool (notify)

Sends a desktop notification with a custom title and message.

Parameters:

• title (string): The title of the notification.
• message (string): The body text of the notification.

Development 👨‍💻

This project uses the rust-mcp-sdk for the MCP server implementation and notify-rust for desktop notification capabilities.

• Adding Tools: Define new tools in src/tools.rs (structs, #[mcp_tool] macro, call_tool logic) and add them to the tool_box! enum.
• Handler Logic: Update the handler in src/handler.rs if new tools require different parameter handling or if new MCP message types need custom processing.
• Server Configuration: Adjust server settings (port, host, capabilities) in src/main.rs.
• Testing: Run tests with cargo test. Add new tests for new functionality.

License 📄

This project is licensed under the MIT License - see the LICENSE file for details (if one is created, otherwise assume MIT or specify).

Acknowledgments 🙏

• rust-mcp-sdk for the MCP SDK.
• notify-rust for the notification capabilities.