mcpd

Linux MCP Server — exposes 100+ Linux system administration tools as an MCP (Model Context Protocol) server.

mcpd runs exclusively over standard input/output (stdio) and is designed to be executed by neurond (federation proxy), not exposed directly to the network.

Architecture

┌──────────────────────────────────────┐
│  mcpd (stdio)                        │
│                                      │
│  ┌────────────┐  ┌────────────────┐  │
│  │            │  │  tools/        │  │
│  │ server.rs  │  │                │  │
│  │ (Router)   │  │  system.rs     │  │
│  │            │  │  network.rs    │  │
│  └────────────┘  │  file.rs       │  │
│                  │  container.rs  │  │
│  ┌────────────┐  │  package.rs    │  │
│  │ linux/     │  │  identity.rs   │  │
│  │            │  │  storage.rs    │  │
│  │ systemd.rs │  │  schedule.rs   │  │
│  │ network.rs │  │  security.rs   │  │
│  │ desktop.rs │  │  ...           │  │
│  └────────────┘  └────────────────┘  │
└──────────────────────────────────────┘
         ▲
         │ stdio
         │
    neurond (federation proxy)

• server.rs — MCP server core, handles routing requests natively via stdio
• tools/ — One module per tool domain. Input validation, pure Rust logic
• linux/ — Low-level OS access: D-Bus proxies (systemd, desktop), Netlink, /proc and /sys parsing
• types.rs — Typed #[derive(Serialize)] response structs for all tools (compile-time field safety)
• daemon.rs — PID file management and graceful SIGTERM/SIGINT shutdown
• deploy/mcpd.service — systemd unit for standalone testing and documenting the expected security context

Tools

| Domain | Tools | Description | | ------------- | -------------------------------------------------------- | ----------------------- | | system.* | info, reboot, sysctl, env, uptime | System info and control | | process.* | list, inspect, kill, signal, top, tree, nice | Process management | | service.* | list, status, start, stop, restart, logs, enable | systemd unit control | | log.* | tail, search, stream, units | journald log access | | network.* | interfaces, ports, connections, dns, firewall, routing | Network stack | | file.* | read, write, info, search, mkdir, chmod, tail | File operations | | container.* | list, inspect, logs, exec, start, stop | Docker containers | | package.* | list, search, info, install, remove, update | APT package management | | identity.* | users, groups, whoami | User/group info | | storage.* | disks, mounts, usage, smart | Disk and SMART | | schedule.* | list, add, remove | Crontab management | | security.* | certs, open_ports, suid | Security checks | | hardware.* | pci, usb | Hardware enumeration | | desktop.* | notifications, clipboard, media, windows, settings, apps | Desktop integration | | time.* | info, sync | NTP time info |

Security

• Tool Segregation — Designed to be run behind a proxy like neurond which handles mTLS, authentication, and policy checks.
• Input validation — Shell metacharacters rejected. Path traversal blocked with canonicalization.
• Path allowlist — File operations restricted to safe prefixes. Sensitive files always blocked.
• Localhost only — Executed via stdio locally. Never exposed to the network directly.

Getting Started

Prerequisites

• Linux with systemd (Debian 12 / Ubuntu 22.04+)
• Rust 1.75+
• D-Bus system socket (standard on systemd hosts)
• For container tools: Docker daemon
• For desktop tools: D-Bus session socket

Build & Run

git clone https://github.com/cortexd-labs/mcpd.git
cd mcpd
cargo build --release

# Run locally (uses stdio transport)
cargo run

Server communicates directly via stdio.

Testing

cargo test          # 198 tests
cargo clippy -- -D warnings

Test with the standard MCP Inspector:

npx -y @modelcontextprotocol/inspector
# Choose stdio transport, select mcpd binary path

Related Projects

• neurond — Federation proxy that aggregates mcpd and other MCP servers under namespaced prefixes
• cortexd — Fleet orchestrator (planned)

License

MIT