Journald MCP server

Servidor MCP Journald

Um servidor MCP para acessar logs do journal do systemd.

Recursos

• Listar unidades systemd dos logs do journal
• Listar identificadores syslog dos logs do journal
• Obter data e hora da primeira entrada do journal
• Filtrar entradas do journal por intervalo de data e hora (desde/até)
• Filtrar por unidade systemd ou identificador syslog
• Filtrar por conteúdo da mensagem (correspondência de substring sem diferenciar maiúsculas/minúsculas)
• Interpretação de data e hora em linguagem natural (ex.: "2 horas atrás", "ontem às 15h")
• Listar unidades e identificadores em intervalos de tempo específicos

Instalação

# Install dependencies
uv sync

Uso

Execute como não-root: Dê ao usuário acesso ao grupo systemd-journal usermod -aG systemd-journal $USER

Execute o servidor com:

uv run server.py [OPTIONS]

Opções de CLI

• --transport: Protocolo de transporte a usar (stdio, sse ou streamable-http). Padrão: stdio
• --port: Porta para escutar no transporte HTTP (ignorada para transporte stdio). Padrão: 3002
• --log-level: Nível de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL). Padrão: INFO

Exemplos

1. Executar com transporte stdio (padrão, para clientes MCP que se comunicam via stdin/stdout):

   python server.py
   

2. Executar com transporte HTTP em porta personalizada:

   python server.py --transport streamable-http --port 8080
   

3. Executar com transporte SSE:

   python server.py --transport sse --port 3000
   

4. Executar com registro de depuração:

   python server.py --log-level DEBUG
   

Integração MCP

O servidor fornece os seguintes recursos e ferramentas MCP:

Recursos

• journal://units: Listar unidades systemd únicas dos logs do journal (todo o tempo acessível)
• journal://syslog-identifiers: Listar identificadores syslog únicos dos logs do journal (todo o tempo acessível)
• journal://first-entry-datetime: Obter a data e hora da primeira entrada no journal
• journal://units/{since}/{until}: Listar unidades systemd únicas em um intervalo de tempo especificado
• journal://syslog-identifiers/{since}/{until}: Listar identificadores syslog únicos em um intervalo de tempo especificado

Ferramentas

• get_journal_entries: Obter entradas do journal com filtro de data e hora

  • Parâmetros: since (opcional), until (opcional), unit (opcional), identifier (opcional), message_contains (opcional), limit (padrão: 100)
  • Retorna: Lista de entradas com timestamp, unidade, identificador e mensagem
  • Exemplo: Obter logs das últimas 2 horas contendo "error": since="2 hours ago", message_contains="error"

• get_recent_logs: Obter logs recentes do journal dos últimos N minutos

  • Parâmetros: minutes (padrão: 60), unit (opcional), limit (padrão: 50)
  • Retorna: String formatada das mensagens de log recentes

Formato de Entrada de Data e Hora

O servidor usa interpretação de data e hora em linguagem natural via biblioteca dateparser. Os formatos suportados incluem:

• Tempos relativos: "2 horas atrás", "ontem às 15h", "semana passada", "agora"
• Tempos absolutos: "2024-01-15 14:30", "2024-01-15T14:30:00"
• Mistos: "hoje às 9h", "amanhã às 15h"

Todos os horários são interpretados como UTC e retornados em formato legível: "YYYY-MM-DD HH:MM:SS UTC"

Desenvolvimento

Este projeto usa:

• Python 3.12+
• MCP FastMCP
• systemd-python para acesso ao journal
• Click para interface CLI
• dateparser para interpretação de data e hora em linguagem natural

Estrutura do Projeto

journald-mcp-server/
├── journald_mcp_server/     # Main package
│   ├── __init__.py
│   ├── server.py           # MCP server implementation
│   └── datetime_utils.py   # Datetime parsing and formatting utilities
├── tests/                  # Test suite
│   ├── __init__.py
│   └── test_server.py
├── server.py              # Entry point wrapper
├── pyproject.toml
└── README.md

Executando Testes

python -m pytest tests/