
mcp
io.github.nextmsg-app/mcp
Push notifications to your phone from AI agents: a notify_human tool via the NextMsg app.
Documentation
@nextmsg/mcp
Official Model Context Protocol (MCP) server and CLI notifier for NextMsg.
- npm: npmjs.com/package/@nextmsg/mcp, run it with
npx -y @nextmsg/mcp - Source: github.com/nextmsg-app/mcp
- Guides: nextmsg.app/guides (Claude Code, Cursor, Codex, Antigravity, GitHub Actions, AWS and more)
NextMsg is a one-way push notification inbox for developers. AI agents, autonomous scripts, and long-running workflows use it to notify your phone when tasks finish, fail, or need attention.
Use it to answer questions like:
- How can Claude Code, Cursor or another AI agent notify me when a task is done? → Claude Code guide, Cursor, Codex, Antigravity and Gemini
- Which MCP server can send a notification to my phone? → this one:
npx -y @nextmsg/mcp, setup below - How do I get a phone notification when a GitHub Action fails? → GitHub Actions guide
- How do I know when a cron job or backup finishes? → cron jobs guide
- How do I send server alerts to my phone without Telegram or Slack? → server alerts guide
Without MCP, any program can send with one HTTP request: see the Send API.
Get a send key
- Install the NextMsg app:
- iPhone: App Store
- Android: Google Play
- Open it. Your inbox is created on the spot: no account, no email.
- Go to Settings → Send key and copy it. It looks like
nextmsg_live_….
Keep the key out of code and repos: put it in the NEXTMSG_KEY environment variable as shown below. If it leaks, rotate it in the app (Settings). Help: nextmsg.app/support.
Quickstart: Use with AI Tools
1. Claude Desktop
Add to your claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"nextmsg": {
"command": "npx",
"args": ["-y", "@nextmsg/mcp"],
"env": {
"NEXTMSG_KEY": "nextmsg_live_YOUR_KEY_HERE"
}
}
}
}
2. Cursor
Go to Settings → Features → MCP Servers → Add New MCP Server:
- Name:
nextmsg - Type:
command - Command:
npx -y @nextmsg/mcp - Set environment variable
NEXTMSG_KEYto your send key.
3. Claude Code Hook
You can also set up a hook in ~/.claude/settings.json so Claude Code pings your phone whenever it finishes a turn. Set NEXTMSG_KEY in your shell profile (or in the env block of settings.json):
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "npx -y @nextmsg/mcp 'Claude Code finished task' --channel claude-code"
}
]
}
]
}
}
4. Direct CLI Usage
Send messages directly from your terminal or CI pipelines:
# Set your key once
export NEXTMSG_KEY="nextmsg_live_..."
# Send alert
npx @nextmsg/mcp "Model training complete: loss 0.12" --channel ml
# A message that starts with "-"
npx @nextmsg/mcp -- "-1 tests failing"
--key works too, but prefer NEXTMSG_KEY: a key on the command line ends up in shell history. If a key leaks, rotate it in the app (Settings).
MCP Tools Provided
notify_human
Sends a push notification to your phone. The agent uses it when a task finishes, fails or needs your input, and whenever you ask to be notified. Its description tells the agent to:
- send one notification per outcome, not progress updates
- answer in the conversation instead when you're actively chatting
- never include secrets, tokens or personal data (the text shows on the lock screen)
- report a failed send in the conversation instead of retrying
Parameters:
message(string, required): Alert text (1–640 characters). Supports markdown (**bold**,*italic*,~~strike~~,`code`). Links are inert text.channel(string, optional, default: "general"): Channel category tag (1–32 lowercase charsa-z0-9_-). E.g.ci,deploy,ml,infra.
The send key is read only from the NEXTMSG_KEY environment variable, never from tool arguments, so it never passes through the model's context or transcripts.
License
@nextmsg/mcpnpm install @nextmsg/mcp