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

• Architecture Visualized

• Start Here

• Key Capabilities & Safety Invariants

• Status & Protocol Support

• Installation

• MCP Client Configuration

• Configuration & Profiles

• Tools & Handlers

• End-to-End Operations Lifecycle

• Search And Disambiguation

• Sibling Ecosystem

• Development & Verification

• Third-Party Licenses & Transparency

• Marketing & Target Personas

• Security & Governance

Related MCP server: automation-health-mcp

Architecture Visualized

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

Start Here

Key Capabilities & Safety Invariants

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.

Installation

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.

MCP Client Configuration

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"
      }
    }
  }
}

Configuration & Profiles

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.

Tools & Handlers

• 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.

End-to-End Operations Lifecycle

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

Search And Disambiguation

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.

Sibling Ecosystem

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

Development & Verification

# 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

Third-Party Licenses & Transparency

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: Comprehensive license disclosures, full copyright notices, and local-first compliance assurances are documented in THIRD_PARTY_LICENSES.md.

Marketing & Target Personas

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

Target Personas

Competitive & Landscape Matrix

Detailed marketing positioning, persona user journeys, and discoverability keywords are maintained in MARKETING-LOG.txt.

Security & Governance

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.