Linux MCP Agent Server

A read-only Linux observability MCP server for external Agentic AI clients. Built with Python 3.14.10 and the official MCP Python SDK 2.3.0. Python 3.15.2 is newer, but the pinned MCP SDK and psutil release currently advertise support/wheels through Python 3.14; this project pins the newest runtime line with a validated dependency compatibility baseline. The primary acceptance environment is Ubuntu 24.04 LTS.

Scope

The server exposes:

This repository does not host an LLM or implement the Agent runtime. The external Agent/MCP Client owns model selection, inference, tool selection and provider fallback. No arbitrary shell, destructive system operation, process command line or environment values are exposed.

Related MCP server: homelab-mcp

Architecture

• Python MCP service runs natively on the Linux host under systemd and binds to 127.0.0.1:3000.

• Caddy 2.11.7 terminates TLS and exposes only the MCP endpoint and required protected-resource metadata route to the LAN.

• Keycloak 26.8.1 issues OAuth access tokens; the MCP service validates them using RFC 7662 introspection and exact issuer/resource/audience/scope checks.

• PostgreSQL 18.6 stores Keycloak data only. It is not an application database.

• Docker Compose 5.6.1 runs Caddy, Keycloak and PostgreSQL; the MCP service is not containerized.

Version baseline (checked 2026-11-02)

Exact direct Python dependencies are pinned in pyproject.toml. The uv.lock file is intentionally not fabricated: generate it with uv lock on a network-connected machine, review it, and commit it before deployment. CI currently resolves from exact direct pins until that lockfile is committed.

Local development

Install uv 0.13.6 and Python 3.14.10:

curl --proto '=https' --tlsv1.2 -LsSf https://astral.sh/uv/0.13.6/install.sh | sh
uv python install 3.14.10
uv lock
uv sync --all-groups
cp .env.example .env
set -a; source .env; set +a
uv run python -m linux_mcp_agent

The local .env.example uses AUTH_MODE=disabled and loopback only. Never expose this development mode to the LAN.

Quality checks

uv run ruff check .
uv run pyright
uv run pytest

LAN deployment

See:

• docs/09_ubuntu2404_deployment.md

• docs/08_authorization_tls_design.md

• deploy/keycloak/README.md

• deploy/systemd/README.md

The LAN profile requires AUTH_MODE=keycloak, trusted Caddy internal CA, a configured Keycloak realm/client, and firewall rules limiting TCP 443. The MCP app and Keycloak bind only to loopback; PostgreSQL is internal to Docker. Compose deliberately gates Caddy behind the lan profile: start and validate PostgreSQL/Keycloak and the authenticated MCP service first, then explicitly run docker compose --profile lan up -d caddy.

Security and known acceptance gate

Keycloak 26.8.1 labels Resource Indicators experimental for the newest MCP protocol revision. The server fails closed unless the token has the exact configured MCP audience/resource. Do not disable audience validation to work around an integration problem. Keep LAN exposure closed until a real integration test confirms resource -> aud, introspection claims, required scopes and cross-device TLS trust.

The systemd-journal supplementary group enables journal access but is broader than the MCP alias list; this residual privilege is documented and must be reviewed during deployment.