Labsco
james116blue logo

Journald MCP server

★ 1

from james116blue

Incident forensic with log files analyzing

🔥🔥🔥✓ VerifiedFreeQuick setup

Journald MCP Server

An MCP server for accessing systemd journal logs.

Features

  • List systemd units from journal logs
  • List syslog identifiers from journal logs
  • Get datetime of first journal entry
  • Filter journal entries by datetime range (since/until)
  • Filter by systemd unit or syslog identifier
  • Filter by message content (case-insensitive substring matching)
  • Natural language datetime parsing (e.g., "2 hours ago", "yesterday at 3pm")
  • List units and identifiers within specific time ranges

MCP Integration

The server provides the following MCP resources and tools:

Resources

  • journal://units: List unique systemd units from journal logs (all accessible time)
  • journal://syslog-identifiers: List unique syslog identifiers from journal logs (all accessible time)
  • journal://first-entry-datetime: Get the datetime of the first entry in the journal
  • journal://units/{since}/{until}: List unique systemd units within a specified time range
  • journal://syslog-identifiers/{since}/{until}: List unique syslog identifiers within a specified time range

Tools

  • get_journal_entries: Get journal entries with datetime filtering

    • Parameters: since (optional), until (optional), unit (optional), identifier (optional), message_contains (optional), limit (default: 100)
    • Returns: List of entries with timestamp, unit, identifier, and message
    • Example: Get logs from last 2 hours containing "error": since="2 hours ago", message_contains="error"

  • get_recent_logs: Get recent journal logs from the last N minutes

    • Parameters: minutes (default: 60), unit (optional), limit (default: 50)
    • Returns: Formatted string of recent log messages

Datetime Input Format

The server uses natural language datetime parsing via the dateparser library. Supported formats include:

  • Relative times: "2 hours ago", "yesterday at 3pm", "last week", "now"
  • Absolute times: "2024-01-15 14:30", "2024-01-15T14:30:00"
  • Mixed: "today at 9am", "tomorrow 3pm"

All times are interpreted as UTC and returned in human-readable format: "YYYY-MM-DD HH:MM:SS UTC"

Development

This project uses:

  • Python 3.12+
  • MCP FastMCP
  • systemd-python for journal access
  • Click for CLI interface
  • dateparser for natural language datetime parsing

Project Structure

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

Running Tests

python -m pytest tests/