LinuxServer MCP

Bridge LinuxServer.io knowledge into MCP and GitHub. Audit accurately. Review intelligently. Automate responsibly.

Community MCP server and GitHub review tooling for LinuxServer.io: image discovery, evidence-backed repository audits, request research, container authoring, and deterministic PR review.

Maintained by Blackout Secure for the community. Findings are not official LinuxServer policy, certification, support decisions, or request approvals.

Product and implementation status

The shared policy/audit engine is the core product. MCP and GitHub are first-class interfaces; neither MCP nor AI is required to audit a repository.

Related MCP server: Docker Hub MCP Server

Architecture

                         +-- MCP stdio / HTTP
                         |
Portable policy core ----+-- Local CLI
                         |
                         +-- GitHub Action / deterministic PR review
                         |
                         +-- text / JSON / annotations / SARIF

• packages/mcp-server/src/core/: schemas, inspection, policy v1, findings, suppression, and report formats.

• apps/cli/: bounded local filesystem adapter and CLI.

• apps/github-action/: bounded GitHub reads and Action adapter; no Action-specific policies.

• packages/mcp-server/src/mcp/: MCP interface; services/: data adapters and legacy usage checks.

• worker/ and apps/web/: Cloudflare HTTP and registry UI.

One publishable package and the established npm lockfile are retained. Empty packages, a second package manager, App scaffolds, and write endpoints are deliberately not introduced. See ADR 0001 and contributor instructions.

Local development

Requirements: Node.js 22 or later and npm.

npm ci
npm run build
npm test
npm run lint
npm run typecheck

npm start launches stdio MCP. npm run dev starts the UI; run the Worker separately with npm run dev --workspace=@blackoutsecure/linuxserver-mcp-worker. The UI proxies /api to Worker port 8787.

The dev container installs dependencies and builds the MCP package. VS Code configuration launches the legacy-compatible stdio entry point.

CLI

After building, from the repository root:

npm run audit -- . --format text
node packages/mcp-server/dist/command.js audit . --format json
node packages/mcp-server/dist/command.js audit . --format github
node packages/mcp-server/dist/command.js audit . --format sarif --output linuxserver-mcp.sarif

After publication, the equivalent installed command is linuxserver-mcp audit ., or npx @blackoutsecure/linuxserver-mcp audit ..

For a diff-aware local review, create a JSON array of changed relative paths, then:

linuxserver-mcp review . --changed-files changed-paths.json --format text

Commands never execute or modify repository files. --output creates a new report and refuses to overwrite an existing file. Formats are projections of the same findings. Paths in local reports are relative to the analyzed directory.

Exit codes: 0 analysis completed without crossing the configured threshold, 1 threshold reached, 2 invalid input or runtime/upstream error. A not_applicable report explicitly means no supported container sources were found, not a successful container certification.

--fail-on error|warning|info|none overrides the repository failure threshold. Warning/info thresholds include higher severities; none is an explicit opt-out, never the default. No arguments, or stdio, still starts MCP for existing clients.

Repository policy configuration

Copy the example to .github/linuxserver-mcp.yml. The version is required and unknown keys fail validation.

version: 1
policy:
  profile: recommended
review:
  changed_files_only: true
severity:
  fail_on: [error]
agent:
  enabled: false
  suggestions: false
  automatic_writes: false

Profiles: recommended includes all implemented rules; linuxserver excludes general security/supply-chain advisories; security selects those advisories only. Checks can be disabled individually. Disabled/non-relevant rules are listed in reports.

Suppressions use a stable rule ID, exact relative evidence paths, and a non-empty reason. Suppressed findings remain visible, including SARIF suppressions. Invalid-source rules cannot be suppressed. automatic_writes: true and review_comments: true are rejected; agent settings do not activate an unimplemented agent.

Policy v1

The catalogue checks:

• Explicit generated-file markers against README/build source changes.

• Safe README, Jenkins, and Compose metadata parsing.

• Literal final-stage Dockerfile ports versus README ports.

• Recognized architecture-specific Dockerfiles versus explicit architecture metadata.

• Literal CI test ports versus README ports.

• Compose usage contradicting explicitly unsupported read-only/non-root metadata.

• Explicit s6-rc type definitions and missing longrun scripts in complete snapshots.

• Custom downstream image branding without the documented setting.

• Literal world-writable permissions and remote-script-to-shell pipelines as general security advice/heuristics, not LinuxServer policy.

See rule IDs, sources, applicability, and limitations. Every finding carries policy version, severity, confidence, classification, evidence, source links, and manual remediation. Cross-file findings retain both sides.

Missing metadata stays unknown. There are no universal PUID/PGID, /config, healthcheck, read-only, or non-root requirements in this repository policy engine. Legacy scaffold/usage tools retain their explicitly opinionated project checklists; those are not official requirements.

GitHub Action and PR review

The root action.yml runs a committed standalone bundle. Consumers do not install dependencies or execute files from the reviewed repository.

After the canonical repository is published and a reviewed version exists:

name: LinuxServer Review
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
permissions:
  contents: read
  pull-requests: read
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false
      - uses: blackoutsecure/linuxserver-mcp@v1 # After release; pin a reviewed full SHA in production.
        id: review
        with:
          mode: review
          policy: recommended
          annotate: true
          fail-on: error

No checks: write, comment, contents-write, or App permissions are needed for workflow annotations. A separate optional Code Scanning upload needs security-events: write and the repository's normal fork/Code Scanning permissions. SARIF generation itself requires neither GitHub nor upload permission.

Inputs include path, mode: audit|review, optional policy/threshold overrides, annotate, optional read-only token, and optional changed-files JSON. Review without an explicit path list reads PR files through the fixed GitHub API, checks head/base revisions before and after pagination, and fails if stale or incomplete. Renames include both paths. Subdirectory annotations remain workspace-relative.

Outputs: sarif-file, findings, failed. SARIF and JSON are written under RUNNER_TEMP; summaries respect repository configuration. Findings never produce PR comments, commits, fixes, or custom Check Runs. pull_request_target and mutation modes are rejected.

Use the normal event-revision checkout before review. The Action audits the local snapshot you provide; GitHub revision reads validate the changed-file context, not the identity of arbitrary local edits. Require maintainer review for policy-configuration changes, including suppressions and disabled rules.

MCP tools

All tools are read-only or deterministic drafts. See per-tool inputs, outputs, auth, sources, failures, and examples.

Remote repository tools accept files as data, not host paths or arbitrary repository URLs. CLI-local reading is not exposed through MCP.

Image requests remain best-effort, read-only public research. Optional GitHub authentication enriches Discussions metadata; no basic image/audit operation requires a token. Current matching is keyword-based, not a complete alias/semantic/feasibility system. Closed requests are checked before suggesting drafts, and incomplete searches are disclosed. No low-value comments or automatic submissions are encouraged.

Safety and resource limits

Repository text is data, never instructions. Dockerfiles, YAML, scripts, and Compose are never executed. The core has no filesystem, hosting, or GitHub dependency.

Structured API failures are errors, not empty successful catalogues or negative official-image lookups. Unknown lifecycle/capability fields remain unknown. New findings never include raw secret-bearing source lines. GitHub workflow-command values are escaped.

The legacy public Discussions/known-issue adapters remain best-effort sources, not authoritative policy or a complete supply-chain/security assessment. Multi-isolate rate limiting still requires a deliberate production design; the current Worker limiter is in-memory. See SECURITY.md.

Deployment and publishing

Nothing is deployed or published by importing this repository. Current metadata deliberately advertises no unverified remote endpoint.

• Configure real KV IDs in wrangler.toml, then use root-local npx wrangler commands.

• Store optional GitHub read credentials as deployment secrets, preferably GitHub App credentials in a production design.

• Deploy the Worker, verify /health and /mcp, and build/deploy the UI with VITE_API_BASE_URL set to the actual Worker origin.

• Only then update the website/remote transport metadata in both server.json copies.

LSIO_API_BASE_URL is restricted to the official https://api.linuxserver.io origin; it is not an arbitrary proxy/SSRF escape hatch. CACHE_TTL_SECONDS accepts 1-86400 (default 3600). An optional GITHUB_TOKEN is used for public Discussion reads, never mutations.

npm run release:check validates the workspace; npm run release:pack previews the publishable package; npm run release:sbom emits a CycloneDX SBOM. CI validates the shipped Action bundle and dogfoods the Action. Dependency review, CodeQL, and Dependabot are configured separately.

The Publish workflow is manual and main-only. Prefer npm trusted publishing/OIDC; an npm publishing secret remains a fallback. GitHub Packages uses the repository's package-scoped token. Cloudflare deployment is separately opted in and requires configured IDs, credentials, and VITE_API_BASE_URL.

The npm package, MCP Registry, GitHub Packages, GHCR, GitHub Marketplace/App, and GitHub Releases are distinct. A repository migration transfers none of those automatically. See the operational handover checklist.

Phases

• Current foundation: discovery/request research, policy v1, CLI, stdio/HTTP, read-only Action review, SARIF, fixtures, and protocol/adapter tests.

• Remaining MVP depth: broader authoritative metadata, repository/supply-chain inspection, alias/upstream-aware duplicate detection, and request feasibility. Add rules only with evidence and tests.

• Beta: GitHub App, custom Check Runs, richer PR explanations, authenticated reads, and exact-hash prepared operations. No write feature is implied by this roadmap.

• Advanced: only after authorization and approval tests, approved Discussions/meaningful comments, fork/PR preparation, policy synchronization, and organization adoption.

Any future mutation must prepare, validate, check duplicates/authorization, show the exact operation, obtain explicit human approval bound to its immutable hash, execute, and record the result. Modified operations invalidate approval. Workflow edits require additional scrutiny.

Canonical migration and compatibility

dev is the default development branch. main is retained as the stable baseline; development changes are not automatically promoted to it. CI and CodeQL cover development changes, while publishing remains manual from main.

blackoutsecure/linuxserver-mcp consolidates linuxserver-mcp-registry at 7ad877a, blackoutsecure/linuxserver-mcp-server at eaa5b0c, and blackoutmode/linuxserver-mcp-server at 6eb7188, including its extra local checkout. All source histories and license notices are retained; originals were not deleted or archived.

Version 0.2.0 adds the policy/core interfaces and three tools without renaming the 22 legacy tools. linuxserver-mcp now accepts audit/review commands; no arguments still starts stdio. The installed aliases linuxserver-mcp-registry and linuxserver-mcp-server, and local packages/mcp-server/dist/cli.js, remain stdio-compatible. dist/index.js remains a library entry point.

Contributing and license

See CONTRIBUTING.md and CODE_OF_CONDUCT.md. Keep policy sources explicit, include valid/invalid fixtures, and preserve read-only defaults.

GPL-3.0 for the combined project; original MIT attribution remains in NOTICE. The Action bundle retains third-party license notices next to its entry point. See LICENSE.