ellmos-servercommander-mcp

Alpha Model Context Protocol (MCP) server for local-first server operations: deployment dry-runs, mail configuration status, access-log analysis, and resilient HTTP health checks.

German README: README_de.md

Part of the ellmos-ai family under the open-bricks open-source umbrella.

Quick Navigation

1. Executive Summary & Core Identity

2. Visual Architecture & System Topology

3. Operations Lifecycle & Execution Sequence Flow

4. Target Personas & High-Intent SEO Queries

5. Comparative Matrix vs. Alternatives

6. Key Capabilities & Safety Invariants

7. Start Here & Quick Guidance

8. Status & Protocol Support

9. Installation & Prerequisites

10. MCP Client Configuration & Deployment Modes

11. Configuration & Profiles Specification

12. Tools & Handlers Reference

13. Search, Disambiguation & Discovery Keywords

14. Sibling Ecosystem Matrix

15. Third-Party Licenses & Level 1 SBOM

16. Security Policy & Operational Limits (48h SLA)

17. Development, Verification & CI Matrix

18. Statutory Notice, Liability Limitation & License (§ 521 BGB)

Related MCP server: automation-health-mcp

1. Executive Summary & Core Identity

ellmos-servercommander-mcp is an authoritative, local-first Model Context Protocol (MCP) server engineered specifically for AI coding assistants and autonomous agent platforms (Claude Code, Cursor, Codex, Antigravity, Gemini). It enables agents to safely diagnose server health, analyze web server access logs, inspect mail readiness, and build dry-run deployment plans without exposing production infrastructure to unverified, destructive mutations or arbitrary shell execution.

Every operation is governed by strict local-first and zero-elevation guarantees:

• 100% Local-First & Zero-Egress by Default: Diagnostic parsing and manifest hashing execute locally; zero telemetry and zero unverified outbound network requests.

• Dry-Run & Staging First: Deployment operations calculate SHA-256 tree digests and check target profiles before any remote command is staged.

• Unprivileged Execution (RunAsInvoker): Operates within standard unprivileged user space without requiring root or administrator elevation.

2. Visual Architecture & System Topology

The following diagram illustrates the decoupled layers of ServerCommander, from MCP host transport and Node.js process supervision to Python dispatching, operational engines, and local persistence sinks:

flowchart TD
    subgraph HostLayer ["1. MCP Host & AI Client Layer"]
        Host["MCP Host: Claude Desktop / Claude Code / Cursor"]
    end

    subgraph GatewayLayer ["2. Gateway & Process Supervision Layer"]
        NodeWrapper["Node.js CLI Wrapper (bin/ellmos-servercommander.js)"]
    end

    subgraph CoreLayer ["3. Python MCP Server Core Layer"]
        FastMCP["Python MCP Server (FastMCP Transport stdio)"]
        Dispatcher["Tool Dispatcher & Parameter Validator"]
        i18nEngine["i18n Translation Engine (en, de, es, zh, ja, ru)"]
    end

    subgraph OperationsLayer ["4. Operations & Diagnostics Engines"]
        HTTPProbe["HTTP Health Probe (sc_health_check)"]
        LogAnalyzer["Apache/Nginx Log Analyzer (sc_logs_analyze)"]
        DeployStaging["Deployment Staging & Manifest Planner (sc_deploy / sc_deploy_status)"]
        MailDiagnostics["IMAP/SMTP Safety Diagnostics (sc_mail_*)"]
    end

    subgraph SinkLayer ["5. Local Storage & Audit Sink Layer"]
        SQLiteHist[("Local SQLite Deploy History (deploy-history.db)")]
        JSONReports[("Sanitized JSON Log Reports")]
        AuditSink["Local Diagnostic Outputs & Stdout Stream"]
    end

    Host <-->|"stdio / JSON-RPC"| NodeWrapper
    NodeWrapper <-->|"Child Process Stdio"| FastMCP
    FastMCP --> Dispatcher
    Dispatcher <--> i18nEngine
    Dispatcher --> HTTPProbe
    Dispatcher --> LogAnalyzer
    Dispatcher --> DeployStaging
    Dispatcher --> MailDiagnostics
    DeployStaging -.->|"Optional opt-in persist"| SQLiteHist
    LogAnalyzer -.->|"Optional persist_report"| JSONReports
    HTTPProbe -.-> AuditSink
    MailDiagnostics -.-> AuditSink

3. Operations Lifecycle & Execution Sequence Flow

The following sequence diagram demonstrates the lifecycle of operations dispatched by an AI agent through ServerCommander, showing concurrent HTTP probing, log parsing, and dry-run manifest calculation:

sequenceDiagram
    autonumber
    actor User as AI Assistant / User
    participant Host as MCP Host (Claude / Cursor)
    participant Wrapper as Node.js Wrapper
    participant Server as ServerCommander Server
    participant Handler as Operation Handler
    participant Disk as Local Disk / SQLite Sink
    participant Target as Network Endpoint

    User->>Host: "Check API health and prepare deploy manifest"
    Host->>Wrapper: JSON-RPC request (stdio)
    Wrapper->>Server: Forward request via child process
    Server->>Server: Parse parameters & validate config

    alt HTTP Health Probe
        Server->>Handler: Dispatch sc_health_check
        Handler->>Target: HTTP/HTTPS GET (async worker thread)
        Target-->>Handler: Status code + Latency response
        Handler-->>Server: Health result dictionary
    else Access Log Analysis
        Server->>Handler: Dispatch sc_logs_analyze
        Handler->>Disk: Read access.log & parse entries
        Handler->>Disk: Optional write structured JSON report
        Handler-->>Server: Aggregated log statistics
    else Deployment Staging
        Server->>Handler: Dispatch sc_deploy (dry_run=True)
        Handler->>Disk: Scan local_path & calculate SHA-256 tree
        Handler->>Disk: Optional insert record into deploy-history.db
        Handler-->>Server: Manifest digest & profile readiness
    end

    Server->>Server: Localize response messages (i18n engine)
    Server-->>Wrapper: JSON-RPC response
    Wrapper-->>Host: Formatted stdio output
    Host-->>User: Structured operations summary & next steps

4. Target Personas & High-Intent SEO Queries

ServerCommander MCP bridges the critical gap between hazardous raw shell execution and opaque hosting control panels. It equips AI agents with safe, structured diagnostic capabilities for system administration.

Target Personas

High-Intent Search & SEO Queries

• "mcp server operations tools"

• "mcp deploy dry-run server"

• "mcp access log analyzer"

• "mcp http health check tool"

• "local-first server management mcp"

• "claude code server operations mcp"

• "safe sftp deployment planning mcp"

• "ai assistant server preflight checks"

• "apache nginx log analysis mcp"

• "resilient http health check mcp"

• "sqlite deploy history mcp"

5. Comparative Matrix vs. Alternatives

The 10-dimension matrix below contrasts ServerCommander against common server administration approaches, mapped directly to its runtime and governance invariants (INV-LOCAL-01 through INV-SLA-10):

6. Key Capabilities & Safety Invariants

7. Start Here & Quick Guidance

8. Status & Protocol Support

• Transport: Standard I/O (stdio) via the Python MCP SDK and Node.js process wrapper.

• Package Status: Public alpha package under the ellmos-ai organization.

• Current Core: MCP tool listing, tool dispatch, TOML configuration loader, HTTP health checks, richer access-log analysis with optional persisted JSON reports, and optional local dry-run deployment history.

• Safe Alpha Handlers: sc_deploy builds local SHA-256 manifests, configuration diagnostics, and opt-in SQLite history records in dry-run mode; sc_mail_* reports protocol-specific IMAP/SMTP readiness without opening mail connections by default.

• i18n Localization: Localized MCP tool descriptions, input-schema field descriptions, and unknown-tool errors for en, de, es, zh, ja, ru with automatic English fallback.

9. Installation & Prerequisites

The npm package contains a Node wrapper that starts the Python server. You still need Python 3.10+ and the Python package mcp>=1.0.0.

Option 1: Install From npm

npm install -g ellmos-servercommander-mcp@alpha
ellmos-servercommander

Option 2: Install From Source

git clone https://github.com/ellmos-ai/ellmos-servercommander-mcp.git
cd ellmos-servercommander-mcp
$env:PYTHONIOENCODING = "utf-8"
python -m pip install -e ".[dev]"
python -m pytest -q

Avoid creating a .venv inside cloud-synced folders if your sync client locks files. If you need an isolated environment, create it outside that folder.

10. MCP Client Configuration & Deployment Modes

Global npm Install

{
  "mcpServers": {
    "servercommander": {
      "command": "ellmos-servercommander"
    }
  }
}

npx Without Global Install

{
  "mcpServers": {
    "servercommander": {
      "command": "npx",
      "args": ["-y", "ellmos-servercommander-mcp@alpha"]
    }
  }
}

Direct Python Execution

{
  "mcpServers": {
    "servercommander": {
      "command": "python",
      "args": ["-m", "servercommander.server"],
      "env": {
        "PYTHONPATH": "C:/path/to/ellmos-servercommander-mcp/src",
        "SERVERCOMMANDER_CONFIG_PATH": "C:/path/to/config/servercommander.toml"
      }
    }
  }
}

11. Configuration & Profiles Specification

ServerCommander searches for configuration files in this hierarchical order:

1. Environment variable SERVERCOMMANDER_CONFIG_PATH

2. ./servercommander.toml

3. ./config/servercommander.toml

4. ~/.config/servercommander/servercommander.toml

An annotated template is included at config/servercommander.example.toml.

[server]
name = "servercommander"
log_level = "INFO"
language = "en"

[deploy.profiles.staging]
target = "sftp://staging.example.com/var/www/app"
local_path = "./dist"
protocol = "sftp"
dry_run = true
record_history = true

[mail]
execution_enabled = false
smtp_host = "smtp.example.com"
smtp_port = 587
imap_host = "imap.example.com"
imap_port = 993

Secrets should always be referenced through environment variables, for example $MAIL_PASSWORD or $SFTP_PASSWORD.

12. Tools & Handlers Reference

• sc_health_check: Checks HTTP/HTTPS endpoints and reports status codes, response headers, and latency. Malformed endpoint URLs are captured gracefully as failed checks rather than aborting the batch.

• sc_logs_analyze: Analyzes Apache/Nginx access logs from inline text or local files, reporting HTTP status classes (2xx/3xx/4xx/5xx), total bytes transferred, top referrers, 404/500 error paths, suspicious bot markers, and optional JSON report persistence via persist_report.

• sc_deploy: Creates a dry-run deployment plan with a local SHA-256 manifest and profile diagnostics without performing remote mutations. Nested symbolic links are tracked as skipped_symlinks to prevent unexpected directory traversal.

• sc_deploy_status: Displays configured deployment profiles, profile diagnostics, and recent dry-run deployment records retrieved from the local SQLite history database.

• sc_mail_list, sc_mail_read, sc_mail_send, sc_mail_search: Safe alpha status responses with action-specific IMAP/SMTP readiness diagnostics. With [mail].execution_enabled = true, sc_mail_list executes a read-only IMAP reachability probe (connect + folder listing) by reusing the canonical mail-connector module without reimplementing an IMAP client.

13. Search, Disambiguation & Discovery Keywords

ServerCommander is the ellmos operations MCP server for local-first server administration workflows. Use this repository when searching for:

• MCP server operations tools

• MCP deploy dry-run server

• MCP access log analyzer

• MCP HTTP health check tool

• local-first server management MCP

• Claude Code server operations MCP

• safe SFTP deployment planning MCP

• AI assistant server preflight checks

• Apache Nginx log analysis MCP

• resilient HTTP health check MCP

• SQLite deploy history MCP

It is not the GitHub MCP server, not a generic arbitrary shell-execution MCP server, not a cloud hosting provider control panel, and not an unverified production SFTP/IMAP auto-executor. The current alpha surface is intentionally diagnostic, dry-run first, and safe by default.

14. Sibling Ecosystem Matrix

This MCP server is an integral component of the ellmos-ai ecosystem and the open-bricks open-source software family.

MCP Server Family

AI Infrastructure & Developer Tools

Desktop Software Suite

Our partner organization open-bricks provides desktop productivity applications built for the age of AI:

• File Management: ProFiler, ExplorerPro, CloudLockFixer

• Document Processing: DokuZen, PDFtoPDFocr, FormularErstellen

• Developer Tools: DevCenter, CodeBox, automizer-for-claude-desktop

15. Third-Party Licenses & Level 1 SBOM

ellmos ServerCommander MCP is strictly built upon permissive open-source foundations. We maintain zero hidden telemetry, zero proprietary binary blobs, and zero unverified dynamic dependencies.

• Direct Runtime: Python MCP SDK (mcp>=1.0.0, MIT License, Anthropic PBC), Python Standard Library (PSFL-2.0).

• Node CLI Wrapper: update-notifier (BSD-2-Clause, Sindre Sorhus) for non-intrusive CLI update checks.

• Optional Extensions: paramiko (LGPL-2.1) dynamically imported only when the optional [sftp] extra is explicitly installed.

• Developer Tooling: pytest (MIT), pytest-asyncio (Apache-2.0), ruff (MIT/Apache-2.0), hatchling (MIT).

• Audit Ledger & Level 1 SBOM: Comprehensive license disclosures, full copyright notices, and local-first compliance assurances are documented in THIRD_PARTY_LICENSES.md. Formal repository attribution is preserved in NOTICE.

16. Security Policy & Operational Limits (48h SLA)

For vulnerability reporting, response SLAs, and local-first security invariant details, see our bilingual SECURITY.md.

• Vulnerability Reporting: GitHub Security Advisories or email security@ellmos.ai / security@open-bricks.org.

• Response SLA: Initial triage within 48 hours; status updates within 5 business days.

17. Development, Verification & CI Matrix

# Set UTF-8 encoding
$env:PYTHONIOENCODING = "utf-8"

# Run complete pytest test suite
python -m pytest -v

# Run Ruff linter
ruff check .

# Verify Node CLI smoke test
npm run smoke

# Verify npm packaging (dry-run)
npm pack --dry-run

18. Statutory Notice, Liability Limitation & License (§ 521 BGB)

Statutory Disclaimer (§ 521 BGB Gefälligkeitsrecht)

Dieses Open-Source-Softwareprodukt wird als unentgeltliche Schenkung im Sinne der §§ 516 ff. BGB bereitgestellt. Gemäß § 521 BGB ist die Haftung des Urhebers und der Beitragenden auf Vorsatz und grobe Fahrlässigkeit beschränkt. Ergänzend gelten die nachstehenden Haftungsausschlüsse der MIT-Lizenz.

Nutzung auf eigenes Risiko. Keine Wartungsverpflichtung, keine Verfügbarkeitszusicherung, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Einsatzzweck.

English Summary

This project is an unpaid open-source donation. In accordance with § 521 of the German Civil Code (BGB), liability is restricted strictly to cases of intentional misconduct and gross negligence. Supplemental liability disclaimers are set forth in the MIT License below.

Use entirely at your own risk. No maintenance commitments, no availability guarantees, and no warranties regarding fitness for any particular purpose.

License & Attribution

Distributed under the terms of the MIT License. Copyright (c) 2026 Lukas Geiger. See LICENSE and NOTICE for full details. Third-party licenses and Level 1 SBOM notices are audited in THIRD_PARTY_LICENSES.md.