Agent Notify Chime MCP Server

A lightweight Model Context Protocol (MCP) server that sends push notifications through ntfy. It mirrors the feature set from simple-ntfy-mcp and adds clear setup guides for Codex, VS Code, and Windsurf clients.

Features

• Zero-setup usage via npx or local install
• Sends notifications to any ntfy topic
• Optional title, priority, tags, click actions, and action buttons
• Works with STDIO MCP clients (Codex CLI/IDE, VS Code extensions, Windsurf)

Requirements

• Node.js 18+
• An ntfy topic name (and optional ntfy credentials if you self-host)

Quickstart (local)

npm install
npm run start

This runs the MCP server on stdio. Use the client configuration examples below to connect.

Environment variables

| Variable | Description | Default | | --- | --- | --- | | NTFY_DEFAULT_TOPIC | Default topic to send notifications to | required | | NTFY_BASE_URL | Base URL of the ntfy server | https://ntfy.sh | | NTFY_AUTH_TOKEN | Bearer token for ntfy auth (optional) | empty | | NTFY_USERNAME | Username for Basic auth (optional) | empty | | NTFY_PASSWORD | Password for Basic auth (optional) | empty | | NTFY_REQUEST_TIMEOUT_MS | Request timeout in ms | 10000 |

Tool: send_ntfy

Send a push notification to your configured ntfy topic.

Parameters

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | message | string | yes | The notification message | | topic | string | no | Topic to send to (uses default if not specified) | | title | string | no | Notification title | | priority | number | no | Priority level 1-5 (default 3) | | tags | string[] | no | Array of tags/emojis | | click | string | no | URL to open when clicked | | actions | object[] | no | Action buttons per ntfy docs |

Example tool call

{
  "message": "Build finished successfully",
  "title": "CI",
  "priority": 4,
  "tags": ["white_check_mark", "rocket"],
  "click": "https://example.com/builds/123"
}

Client setup

Use the published package command below:

• Published package: command = "npx", args = ["-y", "agent-notify-chime"]

Codex (CLI + IDE extension)

Codex reads MCP servers from ~/.codex/config.toml and shares this config with the IDE extension (VS Code, Cursor, Windsurf).

Option A: CLI command

codex mcp add agent-notify-chime \
  --env NTFY_DEFAULT_TOPIC=your-topic \
  -- npx -y agent-notify-chime

Option B: Edit config.toml

[mcp_servers.agent-notify-chime]
command = "npx"
args = ["-y", "agent-notify-chime"]

[mcp_servers.agent-notify-chime.env]
NTFY_DEFAULT_TOPIC = "your-topic"

VS Code (Cline extension)

Cline is a popular MCP client for VS Code. It stores MCP settings in cline_mcp_settings.json (open it via the MCP Servers panel).

{
  "mcpServers": {
    "agent-notify-chime": {
      "command": "npx",
      "args": ["-y", "agent-notify-chime"],
      "env": {
        "NTFY_DEFAULT_TOPIC": "your-topic"
      }
    }
  }
}

After editing, restart the server from the MCP Servers panel.

Windsurf (Cascade)

Windsurf reads MCP settings from ~/.codeium/windsurf/mcp_config.json.

{
  "mcpServers": {
    "agent-notify-chime": {
      "command": "npx",
      "args": ["-y", "agent-notify-chime"],
      "env": {
        "NTFY_DEFAULT_TOPIC": "your-topic"
      }
    }
  }
}

Restart Cascade or toggle the server to apply changes.

Implementation notes

• This server uses the MCP SDK over stdio and publishes a single tool: send_ntfy.
• Notifications are sent by POSTing to NTFY_BASE_URL/<topic> with ntfy headers.
• Auth is optional (Bearer token or Basic auth) for self-hosted ntfy servers.

Future improvements (recommended)

• Add attachment support (files, images) via ntfy X-Attach.
• Add retry/backoff for transient HTTP failures.
• Provide a small CLI to validate config/env variables before launching.
• Support ntfy message templating (predefined titles/tags).
• Optional metrics or structured logging for observability.

Publish to npm

1. Ensure you are logged in: npm login
2. Update the version if needed: npm version patch (or minor/major)
3. Publish: npm publish --access public

If you are publishing for the first time, make sure the package name agent-notify-chime is available on npm.

License

MIT