Uptime Kuma MCP Open

MPC do Uptime Kuma desenvolvido por GryfAi. Suporta a maioria das operações somente leitura.

GitHub

Documentação

Build Status

(Contexto: Este repositório pertencia anteriormente a um dos meus projetos paralelos, o GryfAI. Esse projeto foi descartado e a propriedade foi transferida para mim, pessoalmente. Ele ainda é oferecido sob a mesma licença BSL.

Vamos modificar as informações de contato e a licença será mais aberta. No entanto, gostaria de reconhecimento e atribuição pelo trabalho que investi nele.)

mcp-uptime-kuma-open

Esta é a versão aberta do nosso servidor MCP do Uptime Kuma. Ela é aberta para uso pessoal e pequenas empresas podem usá-la livremente internamente para suas operações. Consulte nossa licença para mais informações. Esta versão é lançada sob a licença BSL. Oferecemos uma solução hospedada com mais funcionalidades incorporadas na versão de código fechado. Se você quiser a versão mais avançada, entre em contato conosco pelo hello (at) gryfai.com

O repositório ainda está ativo e vamos adicionar conteúdo continuamente. Estamos cientes de que falta testagem, mas já testamos com alguns clientes. Está tudo pronto para uso! Escrever testes é a próxima coisa na nossa agenda.

A versão aberta

Esta versão expõe um conjunto limitado, porém útil, de ferramentas para interagir com o Uptime Kuma por meio da sua ferramenta LLM favorita.

Este servidor fornece estas funções:

  • Recuperação do status dos monitores, tanto todos quanto individuais
  • Obter batidas (beats) do monitor
  • Recuperação de notificações, tanto todas quanto individuais
  • Recuperação de páginas de status, tanto todas quanto individuais
  • Recuperação de batimentos cardíacos (heartbeats)
  • Recuperação de tags, tanto todas quanto individuais
  • Recuperação do tamanho do banco de dados
  • Recuperação de manutenção de páginas de status.

Todas essas funções são somente leitura na versão aberta.

Estamos lançando esta versão aberta sob a BSL com mudança de licença para Apache 2.0 no futuro. Tanto para fornecer ferramentas excelentes quanto para garantir que o tempo e o esforço que investimos na manutenção deste repositório não sejam abusados. Você pode, é claro, desenvolver um serviço de código aberto concorrente por conta própria. Incentivamos a concorrência e o código aberto. Estamos apenas regulando o código-fonte para que ele não seja usado em um SaaS concorrente ou em outros projetos para ganho monetário.

Quer mais?

O GryfAi tem uma versão mais poderosa desta ferramenta que pode ser hospedada por meio da nossa solução. Ela inclui recursos como:

  • Adicionar, editar e excluir monitores
  • Adicionar, editar e excluir notificações
  • Adicionar, editar e excluir tags
  • Funcionalidade de manutenção
  • Funcionalidade Docker
  • Gerenciamento de chaves de API
  • Gerenciamento de proxy

Basta entrar em contato conosco: hello (at) gryfai.com

Pré-requisitos

Este projeto usa uv como sistema de build. Certifique-se de ter uv ou pip instalado. Você pode instalar o uv com:

pip install uv

Instalação e uso (usuários finais).

Instale localmente, defina as variáveis de ambiente e deixe seu cliente MCP iniciar o servidor STDIO. Normalmente você não precisa executá-lo manualmente, exceto para depuração.

  1. Crie e ative um ambiente virtual (Python 3.10+).

    • Verifique sua versão do Python executando python3 --version. Se você não tiver Python 3.10 ou mais recente, pode baixá-lo do site oficial do Python.
    • Para criar um ambiente virtual, execute o seguinte comando a partir da raiz do diretório do projeto: python3 -m venv .venv
    • Para ativar o ambiente virtual, execute um dos seguintes comandos, dependendo do seu sistema operacional:
      • Linux/macOS: source .venv/bin/activate
      • Windows: .venv\Scripts\activate
    • Quando o ambiente virtual estiver ativado, o prompt do seu shell geralmente mudará para mostrar o nome do ambiente virtual (por exemplo, (.venv) user@host:...$).

  2. Instale o pacote dentro desse venv: pip install . (ou uv pip install .).

    • Este comando precisa ser executado a partir da raiz do diretório do projeto.

  3. Configure as variáveis de ambiente para sua instância do Uptime Kuma:

    • UPTIME_KUMA_URL (padrão: http://localhost:3001)
    • UPTIME_KUMA_USERNAME
    • UPTIME_KUMA_PASSWORD
    • Você pode definir essas variáveis de ambiente no seu shell, ou pode criar um arquivo .env na raiz do diretório do projeto e adicioná-las lá. Por exemplo: 
      UPTIME_KUMA_URL=http://localhost:3001
UPTIME_KUMA_USERNAME=my-username
UPTIME_KUMA_PASSWORD=my-password
    • Nota: Se você estiver usando um arquivo .env, o servidor carregará automaticamente as variáveis de ambiente dele.

  4. Aponte seu cliente MCP para o comando python -m mcp_uptime_kuma_open.server (exemplos abaixo).

    • Se o seu cliente MCP estiver rodando no mesmo ambiente virtual, você pode usar o comando python -m mcp_uptime_kuma_open.server.
    • Se o seu cliente MCP estiver rodando fora do ambiente virtual, você precisa fornecer o caminho completo para o executável Python no ambiente virtual. Você pode encontrar o caminho completo executando o comando which python (no Linux/macOS) ou where python (no Windows) quando o ambiente virtual estiver ativado. Por exemplo: .venv/bin/python -m mcp_uptime_kuma_open.server.
    • Ao usar o comando mcp add, certifique-se de que o ambiente virtual esteja ativado, ou forneça o caminho completo para o executável Python.

Notas do cliente (todos usam STDIO; as chaves correspondem à documentação atual do cliente):

Gemini CLI

  • A maneira recomendada de adicionar o servidor é executar o seguinte comando: gemini mcp add uptime-kuma python -m mcp_uptime_kuma_open.server
  • Reinicie ou recarregue a CLI para que ela reconheça o novo servidor.
  • Alternativamente, você pode adicionar uma entrada de servidor na configuração MCP do Gemini CLI (mcpServers em ~/.gemini/settings.json):
{
  "mcpServers": {
    "uptime-kuma": {
      "command": "python",
      "args": ["-m", "mcp_uptime_kuma_open.server"]
    }
  }
}

Codex CLI

  • A maneira recomendada de adicionar o servidor é executar o seguinte comando: codex mcp add uptime-kuma python -m mcp_uptime_kuma_open.server
  • Reinicie ou recarregue a CLI para que ela reconheça o novo servidor.
  • Alternativamente, você pode adicionar uma entrada de servidor STDIO na configuração do Codex (~/.codex/config.toml):
[mcp_servers.uptime-kuma]
command = "python"
args = ["-m", "mcp_uptime_kuma_open.server"]
  • Salve e reinicie a CLI do Codex para carregar o servidor.

Claude CLI

  • Adicione o servidor MCP à configuração do Claude CLI (~/.claude.json). É recomendado usar o comando claude mcp add.
  • Se editar o arquivo manualmente, adicione o seguinte ao objeto mcpServers:
{
  "mcpServers": {
    "uptime-kuma": {
      "command": "python -m mcp_uptime_kuma_open.server"
    }
  }
}
  • Execute claude normalmente; ele iniciará o servidor STDIO automaticamente.

Claude Desktop

  • A maneira recomendada de adicionar um servidor MCP é instalá-lo como uma extensão (arquivo .mcpb) ou editar o arquivo de configuração diretamente.
  • O arquivo de configuração está localizado em:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Se editar o arquivo manualmente, adicione o seguinte ao objeto mcpServers:
{
  "mcpServers": {
    "uptime-kuma": {
      "command": "<path-to-root-folder-of-project>/mcp-uptime-kuma-open/.venv/bin/python",
      "args": ["-m", "mcp_uptime_kuma_open.server"]
    }
  }
}
  • Após adicionar o servidor, você deve reiniciar o aplicativo Claude Desktop.

Também oferecemos uma versão comercial HTTP/SSE que pode fornecer melhor desempenho. Sinta-se à vontade para usar a versão aberta STDIO sob a licença fornecida, ou entre em contato conosco se preferir a opção hospedada HTTP/SSE.

Sabemos que alguns clientes às vezes se comportam melhor se você executar diretamente no venv.