mcpField
J
Journald MCP Server

Journald MCP Server

Local
github.com/james116blueData & Analytics1Updated 45w ago
Repository

About Journald MCP Server

Journald MCP Server lets system administrators inspect systemd journal logs through MCP. It provides time, unit, identifier, and message filters, including natural-language date ranges.

Key features

  1. 01List units and syslog identifiers
  2. 02Filter entries by time range
  3. 03Filter by unit or identifier
  4. 04Search message text case-insensitively
  5. 05Parse natural-language dates

Use cases

  1. 01Investigate recent service errors
  2. 02Review logs for a specific unit
  3. 03Search messages within a time window

MCP support

The server exposes journal resources for units, identifiers, and the first entry date, plus tools for retrieving filtered or recent log entries.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "james116blue-journald": {
      "command": "uvx",
      "args": [
        "journald-mcp-server"
      ]
    }
  }
}
Run commanduvx journald-mcp-server

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypijournald-mcp-server0.1.0

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

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

Installation

# Install dependencies
uv sync

Usage

Run as non-root: Give the user systemd-journal group access usermod -aG systemd-journal $USER

Run the server with:

uv run server.py [OPTIONS]
CLI Options
  • --transport: Transport protocol to use (stdio, sse, or streamable-http). Default: stdio
  • --port: Port to listen on for HTTP transport (ignored for stdio transport). Default: 3002
  • --log-level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default: INFO
Examples

  1. Run with stdio transport (default, for MCP clients that communicate via stdin/stdout):

    python server.py

  2. Run with HTTP transport on custom port:

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

  3. Run with SSE transport:

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

  4. Run with debug logging:

    python server.py --log-level DEBUG

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/

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.