ellmos-servercommander-mcp

ellmos ServerCommander MCP logo

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.

Discoverability: Published on npm as ellmos-servercommander-mcp, described for MCP catalogs in server.json, and summarized for AI search/indexing in llms.txt.

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

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

Source Checkout

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

Replace /absolute/path/to/ellmos-servercommander-mcp with your local checkout path.

Server Configuration

Example: config/servercommander.example.toml

Default paths:

• %USERPROFILE%\.servercommander\config.toml
• %USERPROFILE%\.config\servercommander\config.toml
• override with SERVERCOMMANDER_CONFIG

Language can be configured with [server].language, SERVERCOMMANDER_LANG, or SERVERCOMMANDER_LOCALE.

[server]
name = "ellmos-servercommander"
language = "en" # en, de, es, zh, ja, ru

[deploy]
persist_history = false
history_db = "~/.servercommander/deploy_history.db"

[logs]
default_format = "apache" # apache | nginx
persist_reports = false
reports_dir = "~/.servercommander/log_reports"

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

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, document tools, developer utilities, and more.

Development

$env:PYTHONIOENCODING = "utf-8"
$env:PYTHONDONTWRITEBYTECODE = "1"
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.