mcp-systemctl

An MCP (Model Context Protocol) server that reports on and manages systemd services via systemctl and journalctl. Works with any MCP client — Claude Desktop, AI coding agents, or custom tooling.

Quick Start

npm install && npm run build
node dist/index.js

The server speaks JSON-RPC over stdio (the standard MCP transport). Connect it to your MCP client — see MCP_SYSTEMCTL_USAGE.md for client configuration and all available tools.

Tools

Tool	Description
list_services	List systemd units with state/pattern/type filters
get_service_status	Detailed status of a specific service (PID, memory, CPU, uptime, etc.)
list_failed_services	All services in a failed/error state
get_service_logs	Recent journald log entries for a service
service_control	Start, stop, restart, reload, enable, or disable a service

Full parameter details in MCP_SYSTEMCTL_USAGE.md.

---

Architecture

The project follows a clean three-layer separation:

src/index.ts          — Server setup, tool registration
src/tools/*.ts        — Zod input schemas + handler functions (thin glue)
src/systemctl.ts      — Core logic: systemctl/journalctl exec, parsing, formatting

┌──────────────┐     stdio (JSON-RPC)     ┌──────────────────────┐
│  MCP Client  │ ◄──────────────────────► │  mcp-systemctl       │
│              │                          │  (Node.js process)   │
│              │                          │                      │
│              │                          │  tools/*.ts          │
│              │                          │    → systemctl.ts    │
│              │                          │    → systemd         │
└──────────────┘                          └──────────────────────┘

Layer Responsibilities

src/index.ts — Entry point. Creates the McpServer instance, calls server.registerTool() for each tool, then connects to the StdioServerTransport. Adding a new tool means importing its schema and handler and adding one more registerTool call here.

src/tools/ — One file per tool. Each exports:

• A schema object (Zod-defined input parameters with describe() for documentation)
• A handler function conforming to ToolCallback<T> — receives validated args, calls into systemctl.ts, formats the response as MCP content blocks

src/systemctl.ts — The engine. All systemctl and journalctl interactions live here:

• Shell execution via execFile (no shell injection risk)
• Structured result type SystemctlResult<T> — every function returns { ok: true, data } or { ok: false, error, code, stderr }
• Parsers for the systemctl table and key=value output formats
• Human-readable formatters for bytes, nanoseconds, etc.

---

Extending the Server

Adding a new tool takes four steps. This example adds a get_service_unit_file tool that returns a service's unit file contents.

1. Add the core logic in src/systemctl.ts

export async function getUnitFile(name: string): Promise<SystemctlResult<string>> {
  const unitName = name.includes(".") ? name : `${name}.service`;
  // Run: systemctl cat <unit>
  const args = ["cat", unitName, "--no-pager", "-l"];
  return await runSystemctl(args);
}

Use the existing helpers — runSystemctl() and runJournalctl() handle timeouts, permission errors, and missing commands consistently. If you need to parse new output formats, add a parser alongside the existing ones.

2. Create the tool file src/tools/getUnitFile.ts

import * as z from "zod";
import type { ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
import { getUnitFile as getUnitFileCore } from "../systemctl.js";

export const getUnitFileSchema = {
  name: z
    .string()
    .min(1)
    .describe("Service name (e.g. 'sshd', 'cron.service')"),
};

export const getUnitFileHandler: ToolCallback<typeof getUnitFileSchema> = async (args) => {
  try {
    const result = await getUnitFileCore(args.name);
    if (!result.ok) {
      return {
        content: [{ type: "text", text: `Error: ${result.error}` }],
        isError: true,
      };
    }
    return {
      content: [{ type: "text", text: result.data }],
    };
  } catch (err) {
    return {
      content: [{ type: "text", text: `Internal error: ${err instanceof Error ? err.message : String(err)}` }],
      isError: true,
    };
  }
};

The pattern is always: import the core function → call it → check result.ok → format the response. Every handler returns { content: [...], isError?: boolean }.

3. Register the tool in src/index.ts

Add the imports:

import { getUnitFileSchema, getUnitFileHandler } from "./tools/getUnitFile.js";

Add the registration (alongside the existing ones):

server.registerTool(
  "get_unit_file",
  {
    description: "Print the unit file contents of a systemd service.",
    inputSchema: getUnitFileSchema,
  },
  getUnitFileHandler,
);

4. Build and test

npm run build
node dist/index.js

Your MCP client will now discover the new get_unit_file tool automatically — no client-side config changes needed.

Design conventions to follow

Convention	Why
Every core function returns SystemctlResult<T>	Caller always handles errors explicitly; no thrown exceptions
Use execFile, never exec or shell commands	Prevents shell injection through service names or patterns
Schema parameters use .describe()	MCP clients use this description to document the parameter to the LLM
Handlers wrap core calls in try/catch	Last-resort safety net for unexpected errors (not for expected failures)
Permission errors handled in systemctl.ts	Consistent messaging across all tools
Source files use .js extensions in imports	Required by NodeNext module resolution with ESM

What not to do

• Don't put shell execution logic in tool handlers — keep it in systemctl.ts
• Don't throw exceptions for expected failures (missing service, permission denied) — return error responses
• Don't skip error handling on result.ok — every SystemctlResult must be checked
• Don't use any types — the Zod schema provides full type inference
• Don't add new dependencies without evaluating whether the existing patterns suffice

---

Project Structure

mcp-systemctl/
├── src/
│   ├── index.ts          # Server entry point, tool registration
│   ├── systemctl.ts      # Core systemctl/journalctl logic
│   └── tools/
│       ├── listServices.ts
│       ├── getServiceStatus.ts
│       ├── listFailedServices.ts
│       ├── getServiceLogs.ts
│       └── serviceControl.ts
├── dist/                 # Build output (gitignored)
├── node_modules/         # Dependencies (gitignored)
├── MCP_SYSTEMCTL_USAGE.md
├── package.json
├── tsconfig.json
└── .gitignore

---

License

MIT