Ntfy MCP 서버
ntfy 푸시 알림 서비스와 연동하도록 설계된 MCP(모델 컨텍스트 프로토콜) 서버입니다. LLM과 AI 에이전트가 광범위한 사용자 지정 옵션을 통해 기기에 알림을 전송할 수 있도록 지원합니다.
목차
개요
이 서버는 모델 컨텍스트 프로토콜(MCP)을 구현하여 LLM과 외부 시스템 간의 표준화된 통신을 지원합니다. 특히, ntfy 푸시 알림 서비스에 대한 인터페이스를 제공합니다.
Ntfy 는 간단한 HTTP 기반 Pub-Sub 알림 서비스로, 간단한 HTTP 요청을 통해 휴대폰이나 데스크톱으로 알림을 보낼 수 있습니다. 이 MCP 서버를 사용하면 Claude와 같은 LLM 에이전트가 직접 HTTP에 액세스하지 않고도 Ntfy를 통해 알림을 보낼 수 있습니다.
지엑스피1
특징
- MCP 서버 구현: LLM 에이전트와의 원활한 통합을 위해
@modelcontextprotocol/sdk 사용하여 구축되었습니다. - Ntfy 통합: 다음을 지원하여 알림을 보내는 도구(
send_ntfy )를 제공합니다.- 메시지 우선순위 지정(1~5단계)
- 이모티콘 태그
- 클릭 가능한 동작 및 버튼
- 파일 첨부
- 배달 지연
- 마크다운 서식
- 리소스 노출: 구성된 기본 ntfy 주제를 MCP 리소스로 노출합니다.
- TypeScript: 포괄적인 유형 정의를 갖춘 현대적이고 유형이 안전한 코드베이스입니다.
- 구조화된 로깅: 상세하고 회전 가능한 로그를 위해
winston 과 winston-daily-rotate-file 사용합니다. - 구성 관리:
dotenv 사용하여 환경 기반 구성을 쉽게 수행합니다. - 유틸리티 스크립트: 빌드 아티팩트를 정리하고 디렉토리 구조 문서를 생성하기 위한 스크립트가 포함되어 있습니다.
- 오류 처리 및 보안: 견고한 오류 처리, 입력 정리(
sanitize-html ), 보안 필터( xss-filters )를 구현합니다.
빠른 시작
- 필수 조건:
- Node.js(v16+)
- npm 또는 yarn
- MCP 호환 클라이언트(Claude Desktop, Cline 등)
- 설치 및 실행:
# Option 1: Install via npm
npm install -g ntfy-mcp-server
# Option 2: Clone repository and build
git clone https://github.com/cyanheads/ntfy-mcp-server.git
cd ntfy-mcp-server
npm install
npm run build
# Create .env file (optional but recommended)
cp .env.example .env
# Edit .env to set NTFY_DEFAULT_TOPIC
# Start the server
npm start
- MCP 클라이언트 설정에 추가: MCP 클라이언트 설정 파일에 서버를 추가합니다( 구성 참조)
- 도구 사용: 연결되면
send_ntfy 도구를 사용하여 알림을 보낼 수 있습니다.
설치
옵션 1: NPM 패키지(권장)
- 패키지를 전역으로 설치합니다.
npm install -g ntfy-mcp-server
- 또는 프로젝트에 로컬로 설치하세요.
npm install ntfy-mcp-server
옵션 2: 소스에서
- 저장소를 복제합니다.
git clone https://github.com/cyanheads/ntfy-mcp-server.git
cd ntfy-mcp-server
- 종속성 설치:
- 프로젝트를 빌드하세요:
구성
환경 변수
.env.example 기반으로 프로젝트 루트에 .env 파일을 만듭니다.
# Ntfy Configuration
NTFY_BASE_URL=https://ntfy.sh # Optional: Base URL of your ntfy instance
NTFY_DEFAULT_TOPIC=your_default_topic # Optional: Default topic if none specified in requests
# Application Configuration
LOG_LEVEL=info # Optional: Logging level (debug, info, warn, error)
NODE_ENV=development # Optional: Environment (development, production)
MCP 클라이언트 설정
Cline VSCode 확장 프로그램용
다음 구성을 Cline MCP 설정 파일에 추가합니다(macOS에서는 일반적으로 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json 에 위치).
전역적으로 설치된 경우:
{
"mcpServers": {
"ntfy": {
"command": "ntfy-mcp-server",
"env": {
"NTFY_BASE_URL": "https://ntfy.sh",
"NTFY_DEFAULT_TOPIC": "your_default_topic",
"LOG_LEVEL": "info",
"NODE_ENV": "production"
}
}
}
}
소스에서 설치한 경우:
{
"mcpServers": {
"ntfy": {
"command": "node",
"args": ["/path/to/ntfy-mcp-server/dist/index.js"],
"env": {
"NTFY_BASE_URL": "https://ntfy.sh",
"NTFY_DEFAULT_TOPIC": "your_default_topic",
"LOG_LEVEL": "info",
"NODE_ENV": "production"
}
}
}
}
Claude 데스크톱 앱용
Claude Desktop 구성 파일(macOS에서는 일반적으로 ~/Library/Application Support/Claude/claude_desktop_config.json 에 위치)에 다음 구성을 추가합니다.
전역적으로 설치된 경우:
{
"mcpServers": {
"ntfy": {
"command": "ntfy-mcp-server",
"env": {
"NTFY_BASE_URL": "https://ntfy.sh",
"NTFY_DEFAULT_TOPIC": "your_default_topic",
"LOG_LEVEL": "info",
"NODE_ENV": "production"
}
}
}
}
소스에서 설치한 경우:
{
"mcpServers": {
"ntfy": {
"command": "node",
"args": ["/path/to/ntfy-mcp-server/dist/index.js"],
"env": {
"NTFY_BASE_URL": "https://ntfy.sh",
"NTFY_DEFAULT_TOPIC": "your_default_topic",
"LOG_LEVEL": "info",
"NODE_ENV": "production"
}
}
}
}
소스 설치의 경우, /path/to/ntfy-mcp-server/dist/index.js 빌드된 서버 파일의 실제 절대 경로로 바꾸세요. 설정에 맞게 env 변수를 조정하세요.
Ntfy 설정
- ntfy.sh 또는 앱 스토어에서 장치에 ntfy 앱을 설치하세요.
- 앱에서 주제를 구독하세요
- MCP 서버 구성에서 동일한 주제를 사용하세요.
프로젝트 구조
.
├── .env.example # Example environment variables
├── .gitignore # Git ignore patterns
├── LICENSE # Project license (Apache-2.0)
├── package.json # Project metadata and dependencies
├── tsconfig.json # TypeScript compiler configuration
├── docs/
│ └── tree.md # Auto-generated directory structure
├── logs/ # Runtime logs (created automatically)
├── scripts/ # Utility scripts
│ ├── clean.ts # Cleans build artifacts and logs
│ └── tree.ts # Generates the docs/tree.md file
└── src/ # Source code
├── index.ts # Main server entry point
├── config/ # Configuration loading
├── mcp-server/ # MCP server logic, tools, and resources
│ ├── resources/ # MCP resource implementations
│ ├── tools/ # MCP tool implementations
│ └── utils/ # MCP-specific utilities
├── services/ # External service integrations (ntfy)
├── types-global/ # Global type definitions
└── utils/ # General utility functions
도구
send_ntfy
ntfy 서비스를 통해 알림 메시지를 보냅니다.
주요 주장:
| 매개변수 | 유형 | 필수의 | 설명 |
|---|
topic | 끈 | 예 | 게시할 ntfy 주제입니다. |
message | 끈 | 예 | 알림의 주요 내용(최대 4096바이트). |
title | 끈 | 아니요 | 알림 제목(최대 250바이트). |
tags | 끈[] | 아니요 | 분류를 위한 이모티콘 또는 키워드(예: ["warning", "robot"] ). 최대 5개까지 입력하세요. |
priority | 정수 | 아니요 | 메시지 우선순위: 1=최소, 2=낮음, 3=기본값, 4=높음, 5=최대. |
click | 끈 | 아니요 | 알림을 클릭하면 열리는 URL입니다. |
actions | 정렬 | 아니요 | 액션 버튼(보기, http, 브로드캐스트). 최대 3개. |
attachment | 물체 | 아니요 | 첨부 파일의 URL과 이름. |
email | 끈 | 아니요 | 알림을 전달할 이메일 주소입니다. |
delay | 끈 | 아니요 | 배달 지연(예: 30m , 1h , tomorrow ). |
cache | 끈 | 아니요 | 캐시 기간(예: 10m , 1h , 1d ). |
firebase | 끈 | 아니요 | 전달할 Firebase 클라우드 메시징(FCM) 주제입니다. |
id | 끈 | 아니요 | 메시지의 고유 ID입니다. |
expires | 끈 | 아니요 | 메시지 만료일(예: 10m , 1h , 1d ). |
markdown | 부울 | 아니요 | 메시지에서 마크다운 서식을 사용하려면 true 로 설정합니다. |
baseUrl | 끈 | 아니요 | 이 요청에 대한 기본 ntfy 서버 URL을 재정의합니다. |
사용 예:
// Basic notification
{
"topic": "alerts",
"message": "The task has completed successfully."
}
// Advanced notification
{
"topic": "alerts",
"title": "System Alert",
"message": "CPU usage has exceeded 90% for 5 minutes.",
"tags": ["warning", "computer"],
"priority": 4,
"click": "https://server-dashboard.example.com",
"actions": [
{
"id": "view",
"label": "View Details",
"action": "view",
"url": "https://server-dashboard.example.com/cpu"
},
{
"id": "restart",
"label": "Restart Service",
"action": "http",
"url": "https://api.example.com/restart-service",
"method": "POST",
"headers": {
"Authorization": "Bearer token123"
}
}
],
"markdown": true
}
응답 예시:
{
"success": true,
"id": "5ZFY362156Sa",
"topic": "ATLAS",
"time": 1743064235,
"expires": 1743496235,
"message": "This is a test message from the README verification process",
"title": "README Testing"
}
자원
직접 자원
ntfy://default
- 설명: 서버의 환경 변수에 구성된 기본 ntfy 토픽(
NTFY_DEFAULT_TOPIC )을 반환합니다. - 사용법: 클라이언트가 사전 구성 없이도 주요 주제를 발견하는 데 유용합니다.
- 예: LLM 에이전트는 이 리소스에 액세스하여 알림을 보낼 때 자동으로 기본 주제를 사용할 수 있습니다.
- 응답 예시:
{
"defaultTopic": "ATLAS",
"timestamp": "2025-03-27T08:30:25.619Z",
"requestUri": "ntfy://default",
"requestId": "0da963d0-30e0-4dbc-bb77-4bf2dee14484"
}
리소스 템플릿
ntfy://{topic}
- 설명: 특정 ntfy 주제에 대한 정보를 반환합니다.
- 매개변수:
topic - ntfy 주제의 이름. - 사용법: 기본값 이외의 주제에 대한 정보를 쿼리하는 데 사용됩니다.
- 응답 예시:
{
"topic": "ATLAS",
"timestamp": "2025-03-27T08:30:30.038Z",
"requestUri": "ntfy://ATLAS",
"requestId": "31baf1df-278f-4fdb-860d-019f156a72b0"
}
사용 사례
- 장기 실행 작업 알림 - 데이터베이스 백업, 코드 생성, 데이터 처리 등의 작업이 완료되면 알림을 받습니다.
- 예약된 알림 - 향후 이벤트나 알림에 대한 지연 알림을 설정합니다.
- 경보 시스템 - 모니터링 시스템이나 중요 이벤트에 대한 중요한 경보를 설정합니다.
- LLM의 모바일 알림 - LLM이 귀하의 휴대전화로 직접 알림을 보낼 수 있도록 허용합니다.
- 여러 단계로 구성된 프로세스 업데이트 - 복잡한 프로세스의 각 단계가 완료되면 업데이트를 받습니다.
사용 예
기본 알림
<use_mcp_tool>
<server_name>ntfy-mcp-server</server_name>
<tool_name>send_ntfy</tool_name>
<arguments>
{
"topic": "updates",
"title": "Task Completed",
"message": "Your requested data analysis has finished",
"tags": ["check"]
}
</arguments>
</use_mcp_tool>
동작이 포함된 풍부한 알림
<use_mcp_tool>
<server_name>ntfy-mcp-server</server_name>
<tool_name>send_ntfy</tool_name>
<arguments>
{
"topic": "alerts",
"title": "Critical Error Detected",
"message": "The application has encountered a critical error.\n\n**Error Code**: E123\n\n**Details**: Database connection failed",
"tags": ["warning", "skull"],
"priority": 5,
"actions": [
{
"id": "view",
"label": "View Logs",
"action": "view",
"url": "https://logs.example.com"
},
{
"id": "restart",
"label": "Restart Service",
"action": "http",
"url": "https://api.example.com/restart",
"method": "POST"
}
],
"markdown": true
}
</arguments>
</use_mcp_tool>
사용 가능한 스크립트
npm run build : TypeScript 소스 코드를 JavaScript로 컴파일하여 dist/ 디렉토리에 저장합니다.npm run clean : dist/ 디렉토리를 제거하고 logs/ 디렉토리의 내용을 정리합니다.npm run rebuild : clean 후 build .npm run tree : docs/tree.md 에 디렉토리 트리 표현을 생성합니다.npm start : Node.js를 사용하여 dist/ 디렉토리에서 컴파일된 서버를 실행합니다.npm run watch : 실시간 모니터링을 위해 결합된 로그 파일( logs/combined.log )을 추적합니다.
기여하다
기여를 환영합니다! 프로젝트 개선을 위해 풀 리퀘스트를 제출하거나 이슈를 열어주세요.
- 저장소를 포크합니다.
- 기능 브랜치를 생성합니다(
git checkout -b feature/your-feature ). - 변경 사항을 커밋합니다(
git commit -m 'Add some feature' ). - 브랜치에 푸시합니다(
git push origin feature/your-feature ). - 새로운 풀 리퀘스트를 만듭니다.
버그나 기능 요청이 있으면 저장소에 이슈를 생성하세요.
개발 모범 사례
- TypeScript 모범 사례를 따르고 강력한 타이핑을 유지하세요.
- 새로운 기능에 대한 테스트를 작성하세요
- 종속성을 최신 상태로 유지하세요
- 기존 코드 스타일과 패턴을 따르세요
특허
이 프로젝트는 Apache-2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.
감사의 말