ntfy.sh 알림, 비동기 에이전트 메시징 및 인간 개입(human-in-the-loop) 워크플로우를 위한 MCP 서버입니다.
MCP 클라이언트가 ntfy 토픽에 메시지를 게시하고, 실시간 구독을 유지하며, 별도의 메시징 계층을 구축하지 않고도 답장을 기다릴 수 있는 간단한 방법을 제공합니다.
이 서버는 다음과 같은 경우에 유용합니다:
MCP 연결 에이전트로부터 푸시 알림을 받을 때
사용자와 에이전트 간의 비동기 메시지 교환이 필요할 때
ntfy를 통한 가벼운 인간 승인 또는 회신 루프가 필요할 때
장기 실행 워크플로우를 위한 간단한 알림 채널이 필요할 때
일반적인 흐름:
사용자나 외부 시스템이 ntfy 토픽에 메시지를 게시합니다.
MCP 클라이언트가 wait-and-read-inbox 또는 ntfy://inbox를 통해 메시지를 읽습니다.
에이전트가 send-ntfy를 통해 응답합니다.
사용자가 ntfy 푸시 알림으로 응답을 받습니다.
Related MCP server: Chat Human MCP Server
제목, 우선순위, 태그 및 첨부 파일이 포함된 메시지 게시
실시간에 가까운 전달을 위한 지속적인 구독 유지
서버 재시작 없이 토픽 전환
최근 메시지를 메모리와 디스크에 보관
Bearer 토큰 및 Basic-auth로 보호된 토픽 지원
공개 ntfy.sh와 즉시 연동
전역 설치:
npm install -g nfty-mcp-server또는 npx를 통해 실행:
npx -y --yes nfty-mcp-serverntfy.sh에서 토픽을 생성하거나 재사용하세요. 공개 토픽은 설정이 쉬우므로 고유한 이름을 선택하세요.
Cursor 또는 VS Code의 경우, MCP 설정에 다음을 추가하세요:
{
"mcpServers": {
"nfty": {
"command": "npx",
"args": ["-y", "--yes", "nfty-mcp-server"],
"env": {
"NTFY_TOPIC": "your-topic-name",
"NTFY_BASE_URL": "https://ntfy.sh"
}
}
}
}Claude Desktop의 경우, claude_desktop_config.json에 동일한 서버 항목을 추가하세요.
참고:
NTFY_TOPIC은 필수입니다.
--yes는 프로젝트 디렉토리를 오염시키지 않고 npx 설치를 자체 캐시에 유지합니다.
Cursor, VS Code 또는 Claude Desktop을 재시작하여 MCP 서버가 로드되도록 하세요.
send-ntfy구성된 토픽에 메시지를 게시합니다.
매개변수:
message 필수
title 선택 사항
priority 선택 사항, 1에서 5까지
tags 선택 사항
attachUrl 선택 사항
예시:
{
"message": "Task completed successfully.",
"title": "Task Status",
"priority": 4
}set-ntfy-topic현재 세션의 활성 토픽을 전환합니다.
매개변수:
topic 필수
baseUrl 선택 사항
wait-and-read-inbox구성된 토픽에서 새 메시지를 기다리며, 최소 하나 이상의 메시지가 도착하면 반환합니다.
매개변수:
since 선택 사항
sinceTime 선택 사항
sinceNow 선택 사항, 기본값 true
중요:
많은 MCP 클라이언트가 약 60초의 타임아웃을 적용합니다.
사람의 입력을 기다리는 경우, 클라이언트나 호출하는 에이전트가 타임아웃 시 재시도해야 합니다.
에이전트 채팅 흐름을 위한 권장 프롬프트 동작:
사용자 응답을 기다리는 동안
wait-and-read-inbox가 타임아웃되면, 새 메시지가 도착할 때까지 재시도하세요.
ntfy://inbox구성된 토픽에 대한 최근 메시지를 JSON으로 반환합니다.
예시 형태:
{
"topic": "your-topic",
"baseUrl": "https://ntfy.sh",
"messages": [
{
"id": "message-id",
"time": 1234567890,
"title": "Message Title",
"message": "Message body",
"priority": 3,
"tags": ["tag1"],
"topic": "your-topic"
}
]
}서버는 로그, 캐시 파일 및 잠금 파일을 전용 데이터 디렉토리에 저장하여 현재 프로젝트를 어지럽히지 않습니다.
기본 위치:
macOS / Linux: ~/.nfty-mcp-server/
Windows: C:\Users\<user>\.nfty-mcp-server\
여기에 기록되는 파일:
nfty-messages.json
nfty-debug.log
nfty-process.log
nfty.lock
변수 | 설명 | 기본값 |
| 메시지를 보내고 받을 토픽 | 필수 |
| ntfy 서버 URL |
|
| Bearer 토큰 | 선택 사항 |
| Basic-auth 사용자 이름 | 선택 사항 |
| Basic-auth 비밀번호 | 선택 사항 |
| 초기 백로그 커서 |
|
| 가져오기 타임아웃(밀리초) |
|
| 시작 시 로그/캐시 삭제 |
|
| 기존 서버 인스턴스 종료 |
|
| 데이터 디렉토리 재정의 | 기본 플랫폼 경로 |
| 캐시 파일 재정의 |
|
서버를 직접 구성할 수도 있습니다:
npx nfty-mcp-server --topic my-topic --base-url https://ntfy.sh --auth-token your-token지원되는 인수:
--topic
--base-url 또는 --server
--auth-token
--username
--password
--since
--log-incoming
서버가 구성된 토픽에 대한 지속적인 HTTP 구독을 엽니다.
들어오는 메시지는 해당 실시간 연결을 통해 수신됩니다.
최근 메시지는 메모리에 캐시되고 디스크에 저장됩니다.
MCP 도구는 해당 구독 위에서 전송, 토픽 전환 및 대기/읽기 동작을 노출합니다.
비동기 사용자-에이전트 메시징
장기 실행 작업을 위한 푸시 알림
인간 승인 루프
가벼운 운영자 알림
공유 토픽을 통한 에이전트 간 조정
git clone https://github.com/harshwasan/NFTY-MCP.git
cd NFTY-MCP
npm install
npm test
npm run dev프로젝트 레이아웃:
NFTY-MCP/
src/server.js
tests/server.test.js
package.json메시지가 도착하지 않는 경우:
NTFY_TOPIC을 확인하세요.
토픽이 존재하고 도달 가능한지 확인하세요.
구성된 데이터 디렉토리의 디버그 로그를 검사하세요.
연결 문제:
구성된 NTFY_BASE_URL에 대한 네트워크 액세스를 확인하세요.
토픽이 보호된 경우 인증 설정을 확인하세요.
MIT
Publish a message to the configured ntfy topic (set in mcp.json). Supports optional title, priority (1-5), tags, and attachUrl. After sending, use wait-and-read-inbox to wait for responses.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| title | No | ||
| message | Yes | ||
| priority | No | ||
| attachUrl | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| time | No | |
| topic | Yes | |
| status | Yes | |
| priority | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only describes the action as 'publish' without mentioning side effects, idempotency, permission requirements, or rate limits. The description lacks transparency on common behavioral aspects for a send operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences with essential information front-loaded. The first sentence establishes the core purpose, and the second provides a useful cross-reference. No superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values need not be explained. The description covers the basic operation but omits potential constraints (e.g., message length, priority semantics) and error scenarios. It assumes the topic is configured in mcp.json without discussing what happens if it's not. Completeness is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description partially compensates by listing all optional parameters and noting priority range (1-5). However, it does not explain the purpose of tags or attachUrl, nor does it provide formats or examples, leaving some semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Publish a message to the configured ntfy topic', specifying the verb and resource. It lists supported optional fields (title, priority, tags, attachUrl). This differentiates it from siblings set-ntfy-topic (configuration) and wait-and-read-inbox (response handling).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to use wait-and-read-inbox after sending, providing sequential guidance. It does not discuss when not to use this tool or prerequisites, but the context is clear: it is for sending a message to a preconfigured topic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the ntfy topic for this MCP server session (no restart needed).
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | ||
| baseUrl | No |
| Name | Required | Description |
|---|---|---|
| topic | Yes | |
| baseUrl | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description should disclose behavioral traits. It only mentions 'no restart needed', but does not explain implications of changing topic mid-session, whether the change is persistent, or what happens to ongoing notifications. Lacks detail on side effects and conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action. However, it could be structured to include more detail without being wasteful; currently it is slightly under-specified for a 2-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple tool but fails to address the baseUrl parameter. Completeness is acceptable for a minimal tool but has a clear gap given the presence of an optional parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'topic' parameter implicitly but does not mention the 'baseUrl' parameter at all, leaving its purpose unclear for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Change') and resource ('ntfy topic'), specifying it is for the session and does not require restart. This distinguishes it from siblings send-ntfy and wait-and-read-inbox, which are about message sending and receiving.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (changing topic in session) but does not explicitly state when to use compared to siblings or when not to use it. 'No restart needed' hints at immediate effect but lacks comprehensive guidance on appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Waits for new messages on the configured topic (set in mcp.json) and returns when a new message arrives. Does not return until at least one new message is received. Uses the existing subscription. Note: The MCP protocol has a ~60s client-side timeout that cannot be controlled from the server, but this tool will wait as long as possible within that limit.
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | Cursor to filter messages after this point | |
| sinceNow | No | If true (default), only returns messages sent after this call starts. If false, returns all messages since the cursor. | |
| sinceTime | No | Unix timestamp - filter messages with time >= sinceTime |
| Name | Required | Description |
|---|---|---|
| messages | Yes | |
| newCount | Yes | |
| lastCursor | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it waits indefinitely (subject to timeout), uses existing subscription, and returns only on new message. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the core function, each providing essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's waiting behavior and 3 parameters, the description covers the key aspects including timeout and return condition. Output schema exists, so return values are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond what the input schema already describes for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (wait for new messages) and resource (inbox on configured topic), and distinguishes from siblings (send-ntfy, set-ntfy-topic) which are different tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool blocks until a new message arrives and notes the client-side timeout, providing clear usage context. However, it does not explicitly state when not to use it or compare with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.35send-ntfyset-ntfy-topicwait-and-read-inboxScored across 3 tools
Each tool serves a distinct purpose: sending messages, changing topic, and waiting for incoming messages. No overlap, clear boundaries.
Tool names mix patterns: 'send-ntfy' and 'set-ntfy-topic' use verb-ntfy, but 'wait-and-read-inbox' uses a different structure with 'and'. Inconsistent naming conventions.
Three tools is appropriate for a focused notification server: send, configure topic, and receive. Each tool is necessary and none are redundant.
Core publish/subscribe functionality is covered with send and wait. The set-topic tool adds flexibility. A minor gap is lack of explicit unsubscribe or message history, but not essential for core use.
Push notifications for AI agents - send instant iPhone notifications from any MCP client.
Reach your own phone from an AI agent: notifications, approval questions, reminders, ring, files.
Let your AI agent notify you by email, Slack, Discord, or webhook. One tool: send_notification.
Zero-setup WhatsApp notifications + human-in-the-loop for AI agents — text 'join', send in 60s.
