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
로컬에 설치한 경우 npx나 node.js를 통해 실행할 수 있습니다.

옵션 2: 소스에서

저장소를 복제합니다.
git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-server
종속성 설치:
npm install
프로젝트를 빌드하세요:
npm run build

구성

환경 변수

.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 파일을 참조하세요.

감사의 말

알림 서비스를 제공하는 ntfy.sh
LLM-툴 연결을 활성화하기 위한 모델 컨텍스트 프로토콜
이 프로젝트의 모든 기여자와 사용자

Integrations

Ntfy MCP 서버

목차

개요

특징

빠른 시작

설치

옵션 1: NPM 패키지(권장)

옵션 2: 소스에서

구성

환경 변수

MCP 클라이언트 설정

Cline VSCode 확장 프로그램용

전역적으로 설치된 경우:

소스에서 설치한 경우:

Claude 데스크톱 앱용

전역적으로 설치된 경우:

소스에서 설치한 경우:

Ntfy 설정

프로젝트 구조

도구

send_ntfy

주요 주장:

사용 예:

응답 예시:

자원

직접 자원

ntfy://default

리소스 템플릿

ntfy://{topic}

사용 사례

사용 예

기본 알림

동작이 포함된 풍부한 알림

사용 가능한 스크립트

기여하다

개발 모범 사례

특허

감사의 말

Appeared in Searches

`send_ntfy`

`ntfy://default`

`ntfy://{topic}`