Linux MCP daemon (mcpd)

Linux MCP Daemon

A high-performance, Go-based Model Context Protocol (MCP) daemon (mcpd) designed to securely bridge AI agents directly with the Linux operating system.

Overview

This project implements a zero-dependency (kernel-first) philosophy. It allows AI agents to introspect and interact with the host Linux system directly via raw syscalls and the Virtual File System (/proc, /sys) without requiring bloated third-party parsing libraries.

Communication happens directly between the AI agent and the daemon via Server-Sent Events (SSE) and JSON-RPC over HTTPS on port 9091 (TLS is on by default, with a self-signed certificate generated on first start).

Why

An AI agent that helps run a server needs to see it - load, memory, disks, processes, services, logs, the network - and sometimes to act on it. The usual way is an SSH shell, and a shell is everything at once: any command, any file the account can reach, with sudo all of root, and hard to tell afterwards what was done. mcpd gives the agent typed tools instead of a shell:

• Diagnose without a shell. "Why is the site slow?" - processes/top, memory/usage, disks/usage, logs/journal-control, logs/dmesg, network/connections, services/list answer it, with structured output (json/yaml) the agent doesn't have to scrape from top or df.
• Root per tool, not per session. A user runs every tool as its own OS account; root is granted per tool in mcp-sudo.yaml and limited by paths, network destinations and sysctl keys - "may read /var/log as root and restart services" rather than "is root".
• One agent, one account, one token. Each agent gets its own user, and every call is logged with the user, tool, arguments (secrets redacted) and result - an audit trail of what the agent did.
• Small and self-contained. One static Go binary, reading /proc, /sys and systemd over D-Bus itself; it runs on a bare host, in Docker or in Kubernetes, and linuxctl gives people the same tools as a kubectl-like CLI.

Grant carefully. A root grant is root for an agent that follows instructions found in what it reads. Some grants that look narrow are full root (writes to /etc, services/manage, sysctl writes). Read Permissions and Risks before granting anything.

How It Works

• Every tool/resource call spawns a fresh worker process and exits. There's no long-lived state per call - internal/worker/spawner.go re-execs the mcpd binary itself in worker mode (arguments on stdin, never argv), with syscall.Credential{Uid, Gid, Groups} set to a real OS account resolved via user.Lookup(). This is the actual privilege isolation, not a config flag: an unprivileged user's worker process is a genuinely different Linux UID than a privileged one's.
• `configs/mcp-sudo.yaml` decides, per user and per tool, whether `privileged: true` is honored. Two grants exist for resources specifically (see ARCHITECTURE.md's gotcha section) - one for the resource URI itself, one for the internal worker tool name behind it.
• When `mcpd` runs containerized (configs/daemon.yaml's worker.containerized: true, this project's actual Kubernetes deployment), a privileged worker also joins the real host's mount namespace (setns(CLONE_NEWNS) on /proc/1/ns/mnt, no external nsenter binary) - so privileged: true means root on the real host, not just root inside the daemon's own container image.
• Bearer tokens are salted+hashed in users.yaml (token_salt + token_hash, sha256, constant-time compared; the file is 0600), not stored in plaintext. Users and grants are edited only locally, on the host, via linuxctl mcpd user and linuxctl edit mcpd config (validated like visudo) - there is no MCP tool that edits them, so nothing with just a bearer token can grant itself anything. The running daemon applies changes without a restart through daemon/reload-config, which only re-reads the files and rejects invalid ones (see Daemon User Administration).
• Every read is schema-driven, not hand-listed. linuxctl fetches tools/list/resources/list/resources/templates/list from the live daemon on every invocation and resolves its [keyword] grammar against that - a new tool added server-side is immediately usable client-side with zero code changes.

Features

• Direct AI Interaction: HTTP/SSE transport for immediate agent-to-daemon communication.
• Strict Security: Rate limiting, salted+hashed Bearer token authentication, and directory traversal protection.
• Privilege Separation: Master daemon runs as root, spinning up ephemeral unprivileged/privileged workers based on rules defined in configs/mcp-sudo.yaml.
• High Performance: Uses singleflight deduplication and TTL caching for efficient system introspection.
• Docker & Kubernetes Ready: Fully containerized with a multi-stage Docker build and Kubernetes deployment manifests that allow safe host introspection.

Get started

Install on Linux (systemd)

curl -fsSL https://raw.githubusercontent.com/nucleusv/linux-mcp-daemon/main/scripts/install.sh | sudo bash

Needs sudo and curl on an amd64/arm64 host (in a bare ubuntu/debian container: apt update && apt install -y curl ca-certificates, then pipe to bash as root). This downloads the latest release for your architecture (amd64/arm64), verifies its sha256 checksum, installs mcpd and linuxctl to /usr/local/bin, writes clean configs to /etc/mcpd/configs (no default users or tokens), creates a first user mcp and prints its token once, and starts the mcpd systemd service. Then:

export MCP_SERVER=https://127.0.0.1:9091

export MCP_TLS_FINGERPRINT= export MCP_TOKEN= linuxctl get system os-release linuxctl get processes top

• Upgrade: run the same command again - configs are kept, the service restarts only if mcpd changed. From v0.1.0, grant your first user daemon/reload-config once - see Upgrading.
• Pin a version / name the user: ... | sudo bash -s -- --version v0.1.0 --user alice
• More users: each needs an OS account of the same name - see Adding more users.
• Uninstall: ... | sudo bash -s -- --uninstall (add --purge to delete /etc/mcpd; the mcp OS account stays - sudo userdel -r mcp)
• Packages: .deb and .rpm for amd64/arm64 on every release - sudo apt install ./linux-mcp-daemon_ _amd64.deb or sudo dnf install ./linux-mcp-daemon- -1.x86_64.rpm, then the next steps it prints.
• Container image: ghcr.io/nucleusv/linux-mcp-daemon (amd64/arm64) - setup steps in the installation docs.
• macOS (CLI only): the same script installs just linuxctl - curl -fsSL .../install.sh | bash -s -- --bin-dir ~/.local/bin, then export PATH="$HOME/.local/bin:$PATH" (not on macOS's default PATH) - to drive a remote mcpd.

mcpd listens on all interfaces over TLS (a self-signed certificate it creates on first start; clients pin its fingerprint). Plain HTTP is off by default - bearer tokens would travel in clear text. Root access for tools is granted per user and per tool in mcp-sudo.yaml.

Full guide: Installation · Connect an AI agent · mcp-sudo.yaml

Development: build from source

1. Build and Deploy the Server (mcpd)

1. Build the Docker image:

   ./scripts/build.sh

1. Deploy to your local Kubernetes cluster:

   ./scripts/deploy.sh

2. Build the Client (linuxctl)

You can build the CLI client directly on your host machine (e.g. macOS):

./scripts/build-cli.sh                  # writes executables/linuxctl

export PATH="$PWD/executables:$PATH" # so the examples below run as written

Installed from a release (install.sh, .deb/.rpm), linuxctl is already on your PATH.

3. Usage (local development)

The daemon runs on port 9091. You can connect via your AI client using SSE, or use the linuxctl CLI tool:

# Set your token as an environment variable

export MCP_TOKEN="your_token_here"

Ping the daemon

linuxctl ping

linuxctl speaks a small verb/group grammar (linuxctl [target-keyword] [args]) and dynamically discovers every tool and resource from the running daemon - there's no separate client-side command list to keep in sync. Full reference: linuxctl docs or man linuxctl. Every example below shows both forms: linuxctl, and the raw MCP JSON-RPC curl call it resolves to - the full per-tool/resource reference with these side by side for every single one lives at MCP API docs.

Calling the API directly with curl

mcpd speaks JSON-RPC 2.0 over HTTP + SSE, not plain request/response HTTP - every call is a two-step handshake: open an SSE stream to get a one-time POST endpoint, then POST the JSON-RPC request there (the actual result streams back on the SSE connection, not in the POST's response body):

# 1. Open the SSE stream in the background and capture the endpoint it prints

curl -N -s --cacert mcpd.crt -H "Authorization: Bearer $MCP_TOKEN" https://localhost:9091/sse &

server sends: event: endpoint / data: /message?session_id=...

2. POST a request to that endpoint

curl -s --cacert mcpd.crt -X POST "https://localhost:9091/message?session_id= " \ -H "Authorization: Bearer $MCP_TOKEN" \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list"}'

3. Watch the SSE stream from step 1 for the matching "id": "1" response

Every example below follows this exact pattern - only the -d payload changes.

Files

# List a directory, as a table (get is the sole read verb - one result or many, same as kubectl)

$ linuxctl get files list /var/log --output table MODIFIED NAME SIZE IS_DIR 2026-09-22 18:38:14 alternatives.log 6522 false 2026-09-22 18:38:10 apt 4096 true ...

```bash

curl -s -X POST "$END