Model Context Protocol (MCP) for systemd

The server directly connects to systemd via its C API and so doesn’t need systemctl to run.

Installation

Compile directly with

  go build -o bin/systemd-mcp systemd-mcp.go
  go build -o bin/gatekeeper gatekeeper/main.go

or use the provided Makefile:

  make build

and install with

  sudo make install

The make install command installs:

• systemd-mcp to /usr/bin/systemd-mcp
• gatekeeper to /usr/sbin/gatekeeper
• Systemd units for gatekeeper.service and gatekeeper.socket
• Polkit policy for gatekeeper

Security

Stdio Transport (Polkit/DBus)

When running over Stdio (default), systemd-mcp uses polkit for authorization. The process runs as the current user.

• Unit Management: Operations like starting or stopping units trigger a polkit request for org.freedesktop.systemd1.manage-units.

• Log Access: systemd-mcp tries to open the whole journal in this order:

  • If running as root or in the same group as the directory /var/log/journal, all journal files are accessible.
  • Else systemd-mcp connects to the gatekeeper via /run/gatekeeper/gatekeeper.socket. This triggers a polkit request for com.suse.gatekeeper.readlog.
  • If the gatekeeper isn’t usable, only the journal files readable by the current user (e.g. its own user-.journal files) are used. The log output contains a hint about this reduced access.

  Read operations over the stdio transport are always authorized, as the calling user runs the server itself; only write operations still trigger a polkit request.

HTTP Transport (OAuth2)

When running over HTTP (using --http), systemd-mcp uses OAuth2 for authorization. You must specify an OAuth2 controller address using --controller.

• OAuth2 Configuration:
  • Audience: systemd-mcp-server
  • Supported Scopes:
    • mcp:read: Allows read-only access (e.g., listing units, reading logs).
    • mcp:write: Allows write access (e.g., starting/stopping units).

If the HTTP server is started as root or in the journal group, it accesses the whole journal directly. Otherwise the gatekeeper is used for log access, provided gatekeeper.socket is available; if it isn’t, only the journal files readable by the current user are shown.

HTTP Transport with authentication

For debugging purposes, the --noauth flag can be used to access the MCP server without authentication. To ensure this is intentional, the flag must be set exactly to ThisIsInsecure.

Self-signed certificates