ellmos ServerCommander

[ellmos ServerCommander MCP emblem]

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.

[License: MIT] [npm version] [CI] [Pytest] [Python] [Node.js] [Platforms] [MCP] [Status: alpha] [Privacy: Local-First] [RunAsInvoker] [Third-Party: Level 1 SBOM] [Contributing: Guide] [Verified: 2026-10-02] [Marketing: Log] [Security: Bilingual Policy] [Ecosystem: ellmos--ai] [open-bricks] [LLM--Ready: llms.txt]

[!NOTE] Discoverability & AI Search: Published on npm as ellmos-servercommander-mcp, cataloged for MCP ecosystems in server.json, glama.json, and smithery.yaml, and indexed for AI/LLM search in llms.txt.

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)

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

ASCII Architectural Topology (Four-View Projection)

========================================================================================             ellmos-servercommander-mcp: Four-View Architectural Topology========================================================================================
[VIEW 1: COMPONENT STRUCTURE & TRANSPORT BOUNDARIES]  +----------------------------------------------------------------------------------+  | 1. MCP Host & AI Client (Claude Desktop / Claude Code / Cursor / Codex)          |  |    - Stdio JSON-RPC transport protocol                                           |  +----------------------------------------------------------------------------------+                                           |                                           | (JSON-RPC via stdio stream)                                           v  +----------------------------------------------------------------------------------+  | 2. Gateway & Process Supervision (bin/ellmos-servercommander.js)                 |  |    - Node.js CLI launcher & process supervisor (update-notifier checks)          |  |    - Working directory isolation: PYTHONSAFEPATH=1 prevents rogue import hijack  |  +----------------------------------------------------------------------------------+                                           |                                           | (Supervised child process stdio)                                           v  +----------------------------------------------------------------------------------+  | 3. FastMCP Dispatcher & i18n Localization Engine (src/servercommander/)          |  |    - FastMCP server lifecycle, tool schema generation & parameter validation     |  |    - Multi-language localization engine (6 locales: en, de, es, zh, ja, ru)      |  +----------------------------------------------------------------------------------+
[VIEW 2: OPERATIONAL ENGINES & DRY-RUN EXECUTION]  +----------------------------------------------------------------------------------+  | 4. Tool Handlers & Diagnostic Engines                                            |  |    - sc_health_check: Non-blocking HTTP/HTTPS probe with timeout & batch error   |  |    - sc_logs_analyze: Sanitized Apache/Nginx access-log parser & threat detector|  |    - sc_deploy / sc_deploy_status: Fail-safe SHA-256 tree hashing & dry-run plan|  |    - sc_mail_list / sc_mail_read / sc_mail_send: Dry-run IMAP/SMTP diagnostics  |  +----------------------------------------------------------------------------------+
[VIEW 3: LOCAL PERSISTENCE & CONCURRENCY MODEL]  +----------------------------------------------------------------------------------+  | 5. Local Storage & Audit Sinks                                                   |  |    - Local SQLite Deploy History (deploy-history.db) with explicit lease release |  |    - Sanitized JSON diagnostic reports (optional persist_report)                 |  |    - Thread-isolated HTTP GET workers preventing event-loop stalling             |  +----------------------------------------------------------------------------------+
[VIEW 4: SECURITY BOUNDARY & ZERO-EGRESS PERIMETER]  +----------------------------------------------------------------------------------+  | 6. Governance & Defense Invariants (INV-LOCAL-01 through INV-SLA-10)             |  |    - RunAsInvoker: 100% unprivileged user mode; zero root/sudo/UAC requirement   |  |    - Zero-Egress by default: zero telemetry, zero unverified background outbound |  |    - Safe Process Isolation: cwd package exclusion, sanitized error messages     |  |    - 48h Response SLA & statutory liability limitation (§ 521 BGB)               |  +----------------------------------------------------------------------------------+========================================================================================

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@alphaellmos-servercommander

Option 2: Install From Source

git clone https://github.com/ellmos-ai/ellmos-servercommander-mcp.gitcd 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.

Install with your LLM

Copy the following prompt into your coding agent (Claude Code, Codex, Gemini CLI, Cursor) to install and configure ellmos-servercommander-mcp locally:

Read https://github.com/ellmos-ai/ellmos-servercommander-mcp (README.md and llms.txt)and install ellmos-servercommander-mcp on my system.1. Check prerequisites (Node.js >= 18, Python >= 3.10, mcp >= 1.0.0) and explain what will be installed before running commands.2. Install or clone the repository in an isolated environment (`python -m pip install -e .`), without modifying unrelated projects or overwriting existing MCP client settings without confirmation.3. Run a non-destructive smoke/verification check (`python -c "import servercommander; print(servercommander.__file__)"`) and show me the MCP client configuration snippet (`mcpServers.servercommander`).

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 = truerecord_history = true
[mail]execution_enabled = falsesmtp_host = "smtp.example.com"smtp_port = 587imap_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 and plain-text companion THIRD_PARTY_LICENSES.txt. 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 [email protected] / [email protected].
• 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 suitepython -m pytest -v
# Run Ruff linterruff check .
# Verify Node CLI smoke testnpm run smoke
# Verify npm packaging (dry-run)npm pack --dry-run

For detailed contribution guidelines, Plan D local development workflow, and quality gates, see CONTRIBUTING.md.

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.