ellmos-servercommander-mcp

Alpha MCP server for server operations: deployment dry-runs, mail status, access-log analysis, and HTTP health checks.

German README: README_de.md

Part of the ellmos-ai family.

Architecture Visualized

graph TD
    Client[MCP Host: Claude / Cursor] <-->|stdio / JSON-RPC| NodeWrapper[Node.js Entrypoint]
    NodeWrapper <-->|Spawn subprocess| PyServer[Python MCP Server]
    
    subgraph Tools [ServerCommander Tools]
        PyServer -->|sc_health_check| HTTP[HTTP/HTTPS Endpoint Check]
        PyServer -->|sc_logs_analyze| Logs[Apache/Nginx Access Logs]
        PyServer -->|sc_deploy / sc_deploy_status| Deploy[Dry-Run Manifest & SQLite History]
        PyServer -->|sc_mail_*| Mail[IMAP/SMTP Safe Readiness Diagnostics]
    end
    
    subgraph Storage [Local Storage]
        Deploy -->|Optional persist| SQLite[(SQLite Deploy History)]
        Logs -->|Optional persist| JSONReports[(JSON Log Reports)]
    end

Related MCP server: automation-health-mcp

Start Here

Status

• Transport: stdio via the Python MCP SDK

• Package status: public alpha package under ellmos-ai

• Current core: MCP tool listing, MCP tool dispatch, config loading, 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 SHA256 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

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

Install

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.

Start From Source

$env:PYTHONPATH = "src"
python -m servercommander.server

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

ServerCommander looks for configuration in this 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 be referenced through environment variables, for example $MAIL_PASSWORD or $SFTP_PASSWORD.

Tools

• sc_health_check: checks HTTP endpoints and reports status code plus latency; malformed endpoint URLs are returned as failed checks, so one bad input does not abort a batch

• sc_logs_analyze: analyzes Apache/Nginx access logs from inline text or a local file, including status classes, bytes, referers, error paths, suspicious request markers, and optional JSON report persistence via persist_report

• sc_deploy: creates a deployment plan with a local SHA256 manifest and profile diagnostics, but does not upload yet; readiness checks required fields, manifestable local paths, and supported protocols before optional record_history=true; nested symlinks are reported but excluded so a manifest cannot silently traverse beyond the selected release directory

• sc_deploy_status: shows configured deploy profiles, selected-profile diagnostics, and recent dry-run history 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 and no mail connections by default. With [mail].execution_enabled = true, sc_mail_list runs a live, read-only IMAP reachability probe (connect + list folders) by reusing the canonical mail-connector module — it does not reimplement an IMAP client; message-level read/search stay mail-connector's domain, and SMTP send stays non-executing

Search And Disambiguation

ServerCommander is the ellmos operations MCP server for local-first server administration workflows. Use this repo 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

It is not the GitHub MCP server, not a generic shell-command MCP server, not a hosting provider control panel, and not a production SFTP/IMAP executor yet. The current alpha surface is intentionally diagnostic and dry-run first.

ellmos-ai Ecosystem

This MCP server is part of the ellmos-ai ecosystem — AI infrastructure, MCP servers, and intelligent tools.

MCP Server Family

AI Infrastructure & Developer Tools

Desktop Software

Our partner organization open-bricks bundles AI-native desktop applications — a modern, open-source software suite built for the age of AI. Categories include file management (ProFiler), document tools (DokuZen, PDFtoPDFocr), developer utilities (DevCenter, CodeBox), and more.

Development

$env:PYTHONIOENCODING = "utf-8"
python -m pytest -q
npm run smoke
npm pack --dry-run

Next useful step: add explicitly configured execution adapters for SFTP and IMAP/SMTP while keeping dry-run/status-only defaults.