Ntfy MCP Server

Enviar notificações push via serviço ntfy, permitindo que LLMs e agentes de IA notifiquem seus dispositivos.

Documentação

ntfy-mcp-server

Envie, gerencie e reproduza notificações push do ntfy via MCP. STDIO ou Streamable HTTP.

4 Ferramentas • 1 Recurso

Visão geral

Notificações push por meio da API HTTP pub/sub do ntfy. Publique, atualize e gerencie notificações, consulte o histórico de tópicos em cache e pesquise códigos curtos de emojis para tags a partir de qualquer cliente MCP. Executa como um processo stdio ou como um servidor HTTP Streamable local.

Ferramentas

Ferramenta	Descrição
`ntfy_publish_message`	Envia ou atualiza uma notificação push em um tópico do ntfy.
`ntfy_manage_message`	Limpa ou exclui uma notificação enviada anteriormente por `sequence_id`.
`ntfy_fetch_messages`	Consulta mensagens em cache de um ou mais tópicos com filtros opcionais.
`ntfy_search_emoji_tags`	Pesquisa códigos curtos de tags de emoji do ntfy para uso em `tags`.

Recursos

Recurso	Descrição
`ntfy://{topic}`	Instantâneo de um tópico — últimas 20 mensagens da última hora, além da URL do tópico no navegador.

ntfy_fetch_messages cobre os mesmos dados de tópico com janelas e filtros personalizados quando os padrões fixos do recurso não são suficientes.

Referência de capacidades

`ntfy_publish_message` _ferramenta

Os tópicos são criados na primeira publicação — trate o nome do tópico como um segredo; qualquer pessoa que o conheça pode publicar ou assinar
Cobertura completa dos parâmetros de publicação — title, priority (1–5), tags, click, attach, icon, filename, markdown, delay, email, call, cache, firebase; corpo da mensagem limitado a 4096 bytes (caracteres não ASCII custam mais), corpo vazio assume o padrão do servidor triggered
Até três botões de ação discriminados (view, broadcast, http, copy) por mensagem
Atualize ou substitua uma mensagem enviada anteriormente passando o sequence_id original
A substituição de base_url por chamada encaminha credenciais somente quando corresponde a um servidor registrado (NTFY_BASE_URL ou uma entrada de NTFY_SERVERS); caso contrário, a solicitação sai sem autenticação
Publicações que carregam email, call ou um botão de ação broadcast/http pedem que o usuário confirme o destino específico primeiro — a chamada retorna uma solicitação de confirmação e envia somente quando reemitida com a resposta

`ntfy_manage_message` _ferramenta

operation: clear marca a notificação como lida e a dispensa (os assinantes veem message_clear); delete a remove da gaveta (os assinantes veem message_delete)
Somente acréscimo — a mensagem original permanece no cache; reemitir a mesma operação é seguro, embora um novo evento seja disparado a cada chamada
Cada chamada pede que o usuário confirme o tópico, sequence_id e a operação antes que o evento seja disparado — a primeira chamada retorna essa solicitação de confirmação, e recusar falha com consent_declined
O ntfy.sh aceita um sequence_id desconhecido sem erro; implantações ntfy mais rígidas retornam uma falha de not_found em vez disso

`ntfy_fetch_messages` _ferramenta

Retorna um instantâneo, não um fluxo ao vivo — use-o para confirmar a entrega, reproduzir alertas perdidos ou auditar a atividade do tópico
Consultas de múltiplos tópicos separados por vírgula (ex.: alerts,backups,phil_alerts)
Filtre por since (duração / timestamp / ID da mensagem / all / latest), priority, tags, id, title, message, somente agendadas
Janela padrão 10m, limite padrão de 20 mensagens por resposta, teto rígido de 100 — janelas acima do limite mantêm as limit mensagens mais recentes, listadas da mais antiga para a mais nova
Corpos longos truncados para ~500 caracteres com messageTruncated relatando a contagem descartada; busque novamente com uma mensagem id para ler essa mensagem por completo

`ntfy_search_emoji_tags` _ferramenta

Correspondência de substring contra nomes de tags, sem diferenciar maiúsculas de minúsculas; omita query para listar a referência desde o início em sua ordem documentada
limit padrão 25, máximo 200; offset pagina além do teto usando o totalCount retornado
As strings de tag retornadas conectam-se diretamente ao campo tags de ntfy_publish_message

`ntfy://{topic}` _recurso

Instantâneo fixo — últimas 20 mensagens da última 1 hora, além da URL do tópico no navegador; mesma forma de mensagem normalizada que ntfy_fetch_messages (timestamps ISO 8601, truncamento de corpo de ~500 caracteres)
Para janelas, filtros ou reprodução personalizados, use ntfy_fetch_messages em vez disso

Recursos

Construído sobre @cyanheads/mcp-ts-core: transportes stdio e Streamable HTTP, autenticação plugável (none / jwt / oauth), armazenamento substituível (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), registro estruturado com rastreamento OpenTelemetry opcional.

Específico do ntfy:

Encapsula a API HTTP do ntfy com um cliente ciente de novas tentativas (withRetry + tempo limite por solicitação)
Autenticação com escopo por servidor — as credenciais se vinculam a cada URL base registrada (NTFY_BASE_URL ou uma entrada de NTFY_SERVERS); modos mutuamente exclusivos de token de portador / autenticação básica validados no carregamento da configuração; uma substituição de base_url por chamada encaminha autenticação somente quando corresponde a um servidor registrado
Confirmação do usuário antes de efeitos colaterais que deixam a gaveta de notificações — uma limpeza/exclusão, ou uma publicação carregando email, call ou um botão de ação broadcast/http — aplicada tanto em stdio quanto em Streamable HTTP
Proteção SSRF opcional em substituições de base_url (NTFY_BLOCK_PRIVATE_HOSTS) — bloqueia loopback, RFC 1918, malha RFC 6598, link-local e equivalentes IPv6, e então recusa redirecionamentos; servidores registrados são isentos
Referência de tags de emoji incluída, regenerada do docs/ntfy/emojis.md upstream via scripts/build-emoji-tags.ts

Saída amigável para agentes:

Proveniência — ntfy_publish_message e ntfy_manage_message ecoam de volta o tópico resolvido, ID e timestamp; ntfy_fetch_messages também ecoa o since resolvido e os filtros aplicados
Saídas discriminadas — códigos de reason tipados (consent_declined, forbidden_topic, rate_limited, not_found, payload_too_large e mais) em cada contrato de erro de ferramenta permitem que os chamadores ramifiquem no modo de falha em vez de analisar texto de erro
Orientação de truncamento e paginação — ntfy_fetch_messages e ntfy_search_emoji_tags relatam um sinalizador de truncated além de um notice nomeando o próximo passo exato (amplie since, aumente limit, avance offset) em vez de descartar resultados silenciosamente

Primeiros passos

Adicione o seguinte ao arquivo de configuração do seu cliente MCP. O ntfy.sh público funciona imediatamente sem conta; para tópicos protegidos, gere um token de acesso em https://ntfy.sh/account.

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["ntfy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}

Ou com npx (sem necessidade de Bun):

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ntfy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}

Ou com Docker:

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "NTFY_DEFAULT_TOPIC=your-topic-name",
        "ghcr.io/cyanheads/ntfy-mcp-server:latest"
      ]
    }
  }
}

Para Streamable HTTP, defina o transporte e inicie o servidor:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NTFY_DEFAULT_TOPIC=your-topic bun run start:http
# Server listens at http://127.0.0.1:3010/mcp

Pré-requisitos

Bun v1.4.0 ou superior (ou Node.js v24+).
Um nome de tópico em um servidor ntfy. O ntfy.sh público não requer conta; instâncias auto-hospedadas e tópicos protegidos podem precisar de um token de portador ou credenciais de autenticação básica.

Instalação

Clone o repositório:

git clone https://github.com/cyanheads/ntfy-mcp-server.git

Navegue para o diretório:

cd ntfy-mcp-server

Instale as dependências:

bun install

Configure o ambiente:

cp .env.example .env
# edit .env and set NTFY_DEFAULT_TOPIC (and auth, if needed)

Configuração

Variável	Descrição	Padrão
`NTFY_SERVERS`	Matriz JSON de entradas de `{ baseUrl, authToken? \| authUsername?+authPassword? }` — uma por servidor ntfy. A primeira entrada é a base padrão. A autenticação tem escopo no `baseUrl` da entrada; substituições de `base_url` por chamada que correspondem a uma base registrada encaminham a autenticação desse servidor. Use isso quando precisar de mais de um servidor autenticado em um único processo; tem precedência sobre as variáveis de servidor único abaixo.	—
`NTFY_BASE_URL`	Atalho de servidor único — URL base do servidor ntfy (sem barra final). Usado quando `NTFY_SERVERS` não está definido.	`https://ntfy.sh`
`NTFY_DEFAULT_TOPIC`	Tópico usado quando uma chamada de ferramenta omite `topic`.	—
`NTFY_AUTH_TOKEN`	Token de acesso de portador (`tk_…`) para o atalho de servidor único. Mutuamente exclusivo com `NTFY_AUTH_USERNAME` / `NTFY_AUTH_PASSWORD`.	—
`NTFY_AUTH_USERNAME`	Nome de usuário de autenticação básica para o atalho de servidor único — necessário junto com `NTFY_AUTH_PASSWORD`.	—
`NTFY_AUTH_PASSWORD`	Senha de autenticação básica para o atalho de servidor único — necessária junto com `NTFY_AUTH_USERNAME`.	—
`NTFY_REQUEST_TIMEOUT_MS`	Tempo limite HTTP por solicitação em milissegundos.	`15000`
`NTFY_MAX_RETRIES`	Máximo de tentativas de nova tentativa para falhas upstream transitórias (5xx, rede, 429).	`3`
`NTFY_BLOCK_PRIVATE_HOSTS`	Quando `true`, uma substituição de `base_url` por chamada deve resolver para um endereço público, e seus redirecionamentos não são seguidos. Servidores registrados sob `NTFY_SERVERS` / `NTFY_BASE_URL` são isentos, então um destino LAN deliberado ainda funciona. Ative onde chamadores que você não controla podem alcançar o servidor.	`false`
`MCP_TRANSPORT_TYPE`	Transporte: `stdio` ou `http`.	`stdio`
`MCP_SESSION_MODE`	Modelo de sessão HTTP: `auto`, `stateful` ou `stateless`. Este servidor requer `stateful` sobre HTTP — o prompt de consentimento em chamadas destrutivas e de saída é uma solicitação de múltiplas idas e voltas que um cliente HTTP da era 2025 só pode concluir sobre uma sessão ativa — então um início HTTP com `stateless` é recusado. `auto` resolve para `stateful`; stdio ignora a configuração.	`stateful`
`MCP_HTTP_HOST`	Host HTTP.	`127.0.0.1`
`MCP_HTTP_PORT`	Porta HTTP.	`3010`
`MCP_HTTP_ENDPOINT_PATH`	Caminho do endpoint HTTP.	`/mcp`
`MCP_AUTH_MODE`	Modo de autenticação: `none`, `jwt` ou `oauth`.	`none`
`MCP_LOG_LEVEL`	Nível de registro (RFC 5424).	`info`
`LOGS_DIR`	Diretório para registros baseados em arquivo (somente Node; ignorado em Workers).	`./logs`
`OTEL_ENABLED`	Habilita instrumentação OpenTelemetry (spans, métricas, registros de conclusão).	`false`

Consulte .env.example para a lista completa de substituições opcionais.

Executando o servidor

Desenvolvimento local

Compilar e executar:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Executar verificações e testes:

bun run devcheck     # Lint, format, typecheck, security, changelog sync
bun run test         # Vitest test suite
bun run lint:mcp     # Validate MCP definitions against spec

Docker

docker build -t ntfy-mcp-server .
docker run --rm -e NTFY_DEFAULT_TOPIC=your-topic -p 3010:3010 ntfy-mcp-server

O Dockerfile usa como padrão o transporte HTTP, modo de sessão com estado e registra em /var/log/ntfy-mcp-server. Dependências de pares OpenTelemetry são instaladas por padrão — compile com --build-arg OTEL_ENABLED=false para omiti-las.

Estrutura do projeto

Diretório	Finalidade
`src/index.ts`	Ponto de entrada do `createApp()` — registra ferramentas e recursos, inicializa serviços.
`src/config`	Análise de variáveis de ambiente específicas do servidor (`NTFY_*`) com Zod.
`src/mcp-server/tools`	Definições de ferramentas (`*.tool.ts`).
`src/mcp-server/resources`	Definições de recursos (`*.resource.ts`).
`src/services/ntfy`	Cliente HTTP ntfy, tipos e classificador de erros.
`src/services/emoji-tags`	Referência de códigos curtos de emoji incluídos e serviço de consulta.
`docs/ntfy`	Documentação espelhada da API ntfy upstream (commit fixado em `SOURCES.md`).
`tests/`	Testes unitários e de integração espelhando `src/`.

Guia de desenvolvimento

Consulte CLAUDE.md para diretrizes de desenvolvimento e regras arquiteturais. A versão resumida:

Handlers lançam exceções, o framework captura — sem try/catch na lógica das ferramentas
Use ctx.log para registro com escopo de requisição, ctx.state para armazenamento com escopo de tenant
Encapsule chamadas de API externas: valide os dados brutos → normalize para o tipo de domínio → retorne o esquema de saída; nunca invente campos ausentes
Contratos errors[] por ferramenta permanecem inline — a repetição é intencional para localidade

Contribuindo

Issues são bem-vindas. Execute as verificações e os testes antes de enviar:

bun run devcheck
bun run test

Licença

Apache-2.0 — consulte LICENSE para detalhes.

Ntfy MCP Server

Documentação

ntfy-mcp-server

Visão geral

Ferramentas

Recursos

Referência de capacidades

ntfy_publish_message ferramenta

ntfy_manage_message ferramenta

ntfy_fetch_messages ferramenta

ntfy_search_emoji_tags ferramenta

ntfy://{topic} recurso

Recursos

Primeiros passos

Pré-requisitos

Instalação

Configuração

Executando o servidor

Desenvolvimento local

Docker

Estrutura do projeto

Guia de desenvolvimento

Contribuindo

Licença

`ntfy_publish_message` _ferramenta

`ntfy_manage_message` _ferramenta

`ntfy_fetch_messages` _ferramenta

`ntfy_search_emoji_tags` _ferramenta

`ntfy://{topic}` _recurso