MCPal

MCPal

Lightweight MCP server for native desktop notifications with action buttons, text replies, and LLM-aware icons.

Compatible with any MCP client.

Usage

Add to your MCP Config manually:

// JSON
{
  "mcpServers": {
    "mcpal": {
      "command": "npx",
      "args": ["mcpal@latest"]
    }
  }
}

Or TOML (Codex):

// TOML
[mcp_servers.mcpal]
command = "npx"
args = ["-y", "mcpal@latest"]

Codex CLI

Add MCPal directly via the CLI:

codex mcp add mcpal -- npx -y mcpal@latest

Claude Code

Add MCPal directly via the CLI:

# Project scope (current project only)
claude mcp add mcpal -- npx -y mcpal@latest

# User scope (available in all projects)
claude mcp add mcpal --scope user -- npx -y mcpal@latest

Configuring Proactive Notifications

MCPal includes built-in MCP instructions that tell clients *how* to use notifications. To configure *when* your assistant should proactively notify you, add this to your client instruction file. This should either be `AGENTS.md` or `CLAUDE.md` based on your model:

## Post Task Completion Hook

ALWAYS use MCPal MCP tool (if available) to notify me when you finish any tasks (this includes reading files, investigating, coding). You should use this tool before you terminate conversations. Refer to tool instructions precisely to craft your response.

Customize this based on your preferences - some users want frequent updates, others only want notifications for important decisions.

Other MCP Clients

MCPal works with any MCP-compatible client (Cursor, VS Code with MCP extensions, etc.). The setup varies by client - refer to your client's documentation for adding MCP servers.

Tool: `send_notification`

Send native notifications with optional features.

Parameters

Examples

Simple notification:

{
  "message": "Build complete!",
  "title": "CI/CD"
}

With actions:

{
  "message": "Deploy to production?",
  "title": "Deployment",
  "actions": ["Deploy", "Cancel"],
  "dropdownLabel": "Choose"
}

With reply:

{
  "message": "What should I name this file?",
  "title": "Question",
  "reply": true
}

You can reply directly from the notification without switching apps:

Tool Result Contract

`send_notification` now returns a dual contract:

• Canonical machine output via `structuredContent` (recommended for parsing)
• Backward-compatible text output in `content[0].text`

Structured fields:

• `status`: `"sent"` or `"error"`
• `title?`: Notification title
• `message?`: Message actually sent after sanitization
• `response?`: Notification response (`"timeout"`, clicked action, etc.)
• `activationType?`: Activation source (`"replied"`, `"actionClicked"`, etc.)
• `reply?`: User free-form reply
• `error?`: Error message when `status` is `"error"`
• `sanitized?`: `true` when MCPal had to sanitize or truncate inputs

Legacy text is still line-based, but each value is JSON-encoded on a single line for parser safety, for example:

status: "sent"
title: "MCPal"
message: "Line 1\nLine 2"
response: "timeout"

Input Sanitization

Before delivery, MCPal applies best-effort sanitization to reduce notifier/parser failures:

• Normalize line endings: `\r\n` / `\r` -> `\n`
• Remove unsafe control chars (keeps `\n` and `\t`)
• Truncate limits:
  • `title`: 256 chars
  • `message`: 4000 chars
  • `actions`: max 3 items, each 64 chars
  • `dropdownLabel`: 64 chars

LLM-Aware Icons

MCPal detects which MCP client is calling the tool and displays the appropriate icon in notifications.

This works via the MCP protocol's client identification - each client sends its name during initialization.

Adding New Client Icons

To add support for a new LLM client, add a PNG to `src/assets/clients/` and update the mapping in `src/notify.config.ts`.

Icon Specifications:

Development

# Install dependencies
pnpm install

# Build (required after clone - sets up desktop notification app)
pnpm run build

# Type check
pnpm run typecheck

# Lint
pnpm run lint:fix

# Format
pnpm run format:fix

MCP Inspector

Test the MCP server interactively using the official inspector:

pnpx @modelcontextprotocol/inspector node dist/index.js

This opens a web UI where you can:

• View available tools and their schemas
• Send test notifications with different parameters
• See raw MCP protocol messages

Local Dev Troubleshooting

If you run a local build directly from `dist/index.js` and notifications are not working, make sure the entrypoint is executable:

chmod +x dist/index.js

Testing Notifications

Test the notification system directly without running the MCP server:

# Simple notification (default)
pnpm run test:notification

# With action buttons
pnpm run test:notification actions

# With reply input
pnpm run test:notification reply

# Run all tests
pnpm run test:notification all

License

Code: MIT License

MCPal Icon & Branding: © 2025 All Rights Reserved. The MCPal logo and icon designs may not be used without permission.