Skip to main content
Glama

Starmux — All-in-One Self-Hosted Remote MCP Server & Gateway

One turnkey daemon for remote filesystem, terminal, background processes, auth, and stdio MCP multiplexing—no manual component assembly required.

All-in-One Remote MCP Server · Streamable HTTP Gateway · Built-in Filesystem, Terminal, Process & Git Tools · stdio Multiplexer · MIT

Why Starmux? · All-in-One vs. DIY Stacks · Quick Start · Auth & Multi-Instance Permissions · Use Cases · macOS App · Documentation


Why Starmux?

Cloud AI assistants (like ChatGPT Web, Claude, or Doubao) are isolated in the browser, and many desktop coding agents (like WorkBuddy, Cursor, Claude Code, Codex, Antigravity, DSH-Harness, Kimi Code, Minimax Code, or ZCode) lack native apps for headless Linux servers or ARM64 edge boards.

Normally, solving this requires manually assembling 3–4 separate open-source tools: a local tool server (DesktopCommanderMCP or filesystem-mcp), a stdio-to-HTTP transport adapter (supergateway or mcp-proxy), an authentication/aggregation gateway (MCPHub or ContextForge), and a process supervisor.

Starmux (Star topology + Multiplexer) replaces that entire fragmented chain with a single, turnkey self-hosted daemon (starmux up):

Traditional DIY Stack:  [Filesystem/Terminal MCP] + [supergateway / mcp-proxy] + [Auth/Aggregator Gateway] + [Supervisor]
Starmux (All-in-One):   [                   Single 'starmux up' Daemon (127.0.0.1:18893/mcp)                   ]
  • Turnkey Filesystem, Diff File Editing, Terminal & Process Management (Desktop Commander Engine): Out of the box—with zero external MCP servers to install—AI clients can read/write local files (read_file, write_file, list_directory), run ripgrep code searches (start_search), perform surgical diff edits (edit_block), control interactive PTY/Shell terminal sessions (start_process, interact_with_process, read_process_output), manage background processes (list_processes, kill_process, force_terminate), and run Git workflows.

  • Operate Headless Linux, NVIDIA Jetson (ARM64), macOS & Windows Remotely: Desktop AI clients like WorkBuddy or ChatGPT have no native Linux or ARM64 desktop app. Run Starmux on your target Linux workstation, NVIDIA Jetson Orin, or server, and drive its filesystem and terminal remotely from your Mac/PC or browser.

  • Built-in stdio-to-Streamable HTTP Bridge & Multi-Server Aggregator: Exposes a native Streamable HTTP (/mcp) endpoint directly and can multiplex your own extra local stdio MCP servers (upstreams) behind the same port—no separate supergateway or mcp-proxy wrapper needed.

  • Integrated Read-Only Safety Gate, Revocable API Keys, OAuth 2.0 & Local Admin UI: Starts in Global Read-Only mode (readOnly) by default so AI can safely inspect files and directories without running shell commands or modifying disk. Switch to Coding mode (--code) when needed, lock down remote access with per-client revocable Bearer API keys or OAuth 2.0 + PKCE, and manage everything from the CLI or private local Admin UI / Web Dashboard.


Related MCP server: AKIMCP

All-in-One vs. Fragmented DIY Stacks

Instead of wiring together separate tool backends, transport bridges, and auth proxies—or deploying heavy control planes that still lack host tools—Starmux provides a unified end-to-end runtime:

Capability

Starmux (All-in-One Daemon)

DIY Stack (DesktopCommanderMCP + supergateway / mcp-proxy)

Pure MCP Gateways (MCPHub / ContextForge / MetaMCP)

SSH MCP Bridges (ssh-mcp / ssh-mcp-server)

Vendor-Hosted Relays (Hosted Remote Desktop Commander)

Built-in Filesystem, Diff Edit, Terminal & Process Tools

✅ Built-in (25+ tools)

⚠️ Requires separate tool server

❌ None (must wire external servers first)

✅ Via OpenSSH / SFTP

✅ Built-in

Native Streamable HTTP /mcp Endpoint

✅ Built-in

⚠️ Requires transport adapter

✅ Built-in

❌ Local stdio only (no direct Cloud AI HTTP)

✅ Hosted cloud endpoint

Works with Cloud/Browser AI (ChatGPT Web, Claude)

✅ Direct HTTPS or Tunnel

⚠️ Manual proxy + auth wiring

✅ With external tool backends

❌ Requires local stdio host

✅ Via vendor cloud

Headless Linux x64 / ARM64 & NVIDIA Jetson Support

✅ Single-command CLI (starmux up)

⚠️ Manual multi-process setup

⚠️ Often requires Docker / DB stack

✅ Via SSH target

⚠️ Depends on host agent

Enforced Global Read-Only vs. Coding Mode Switch

✅ 1-command switch (--read / --code)

❌ No unified read-only gate

❌ No host-tool read/code mode

❌ Relies on OS SSH user

⚠️ Vendor-defined

Per-Client Revocable Bearer API Keys & OAuth 2.0

✅ Built-in + Local Admin UI

❌ Requires external auth proxy

✅ Built-in

❌ SSH keys only

✅ Vendor OAuth

Multiplex Extra Local stdio MCP Servers (upstreams)

✅ Built-in namespaced router

⚠️ Adapter-dependent

✅ Built-in

❌ No

❌ No

100% Self-Hosted (Zero Mandatory Third-Party Relay)

✅ Your network & keys

✅ Self-hosted

✅ Self-hosted

✅ Self-hosted

❌ Traffic routes via vendor relay


Quick Start

1. Install

Requires Node.js 22.12+ on macOS, Linux (x64 / ARM64 / NVIDIA Jetson), or Windows.

npm install -g starmux

(Upgrading? Run starmux down before installing the new version—see the Upgrade Guide.)

2. Start in your project directory

cd /path/to/your/project

# Option 1: Read-only mode (default — safely inspect files, folders & code)
starmux up

# or, Option 2: Coding mode (enable file edits, interactive terminal, process management & Git)
starmux up --code

Starmux starts in the background on http://127.0.0.1:18893/mcp with Authentication: None by default for immediate local connection:

● Starmux is running  (instance: default)
  Instance        <instance UUID>
  Listen          http://127.0.0.1:18893/mcp  (this computer only)
  Project         /path/to/your/project
  Mode            Read-only (global · OS account)  (run 'starmux up --code' to enable edits & shell)
  Auth            None (no token required)

(Switch between Read-only and Coding permissions anytime with starmux up --code and starmux up --read.)

3. Expose for Remote / Cloud AI (Skip if your AI client runs on this same computer)

Starmux defaults to 127.0.0.1:18893. Choose direct LAN access or a proxy/tunnel according to your network.

Network scenario

Setup

Client URL

A1. Trusted LAN / Tailscale / WireGuard (Direct HTTP)

starmux up --allow-lan

http://<lan-or-tailscale-ip>:18893/mcp

A2. Public Domain / Cloud AI Requiring HTTPS

Keep starmux up --local; use Caddy or Tailscale Serve/Funnel for HTTPS

https://mcp.example.com/mcp

B. Behind NAT / CGNAT

Keep starmux up --local; run an outbound tunnel

Your tunnel's HTTPS URL ending in /mcp

A1 — Direct LAN / virtual-network access:

starmux up --allow-lan  # Listen on 0.0.0.0; no Caddy or tunnel needed
starmux status          # Show detected LAN / Tailscale IPv4 MCP URLs
starmux up --local      # Return to loopback only (alias: --no-allow-lan)

The network mode is saved per instance; a later starmux up keeps it. Switching modes on a running instance restarts its Worker. --allow-lan listens on all IPv4 interfaces, so limit network reachability to your intended clients. Authentication settings stay unchanged; use starmux auth key "My AI Client" for per-client credentials. /access, /dashboard, and all other management routes remain local to 127.0.0.1:<port> or localhost:<port>.

A2 — Public domain / HTTPS:

starmux up --local
caddy reverse-proxy --from mcp.example.com --to 127.0.0.1:18893

Caddy and Tailscale Serve/Funnel can forward the original domain Host without rewriting it. Enable API key, OAuth, or authenticated ingress for public access. Keep the original public Host so forwarded requests cannot reach local management pages.

B — Outbound tunnel behind NAT:

cloudflared tunnel --url http://127.0.0.1:18893

No Host rewrite option is needed. Other tunnels such as ngrok, frp, and SSH remote forwarding can also preserve the original Host on /mcp, /healthz, and OAuth resource discovery routes. For OpenAI Secure MCP Tunnel and other networking setups, see Installation & Networking.

4. Connect your AI client

With default settings (Auth: None), connect your AI client using any of the 3 options below:

Option 1 — Ask your AI coding agent to add it for you (Zero manual config)

For agentic coding clients (Claude Code, Antigravity, Codex, Cursor, WorkBuddy, DSH-Harness, Kimi Code, Minimax Code, ZCode), send this prompt in the AI chat (replace the URL with your LAN IP, domain, or http://127.0.0.1:18893/mcp):

Create this MCP Server connector:
"starmux": {
  "type": "streamable-http",
  "url": "http://192.168.50.114/mcp"
}

or, Option 2 — AI clients with a Form UI (e.g., ChatGPT Web, Claude, Doubao)

MCP Client Field

Value to Fill In

Transport

Streamable HTTP (or select your Tunnel in ChatGPT Web)

URL

https://mcp.example.com/mcp (Remote HTTPS / Tunnel) — or http://127.0.0.1:18893/mcp (same computer)

Authentication

None (default for local/LAN; use Bearer API Key or OAuth 2.0 for public endpoints)

or, Option 3 — Manually paste into mcp.json

  • Same-computer connection (or when using local ssh -L port forwarding):

    {
      "mcpServers": {
        "starmux": {
          "type": "streamable-http",
          "url": "http://127.0.0.1:18893/mcp"
        }
      }
    }
  • Remote / LAN connection (via --allow-lan, Direct Proxy or Tunnel — do NOT use 127.0.0.1 across separate machines):

    {
      "mcpServers": {
        "starmux": {
          "type": "streamable-http",
          "url": "https://mcp.example.com/mcp"
        }
      }
    }

Securing Remote Access: Auth & Multi-Instance Permissions

When exposing Starmux beyond 127.0.0.1, lock down your endpoint with per-client credentials and permission controls:

1. Per-Client Bearer API Keys & OAuth 2.0

  1. Per-Client Bearer API Keys (with instant revocation & private Admin UI): Create a named credential for each AI client so you can audit or revoke them independently without exposing the local admin interface:

    starmux auth key "My AI Client"
    starmux auth                    # List active API keys, OAuth sessions, and auth status
    starmux dashboard               # Open the private local Admin UI / Web Access Console (127.0.0.1 only)

    Then add the Authorization header to your client's mcp.json:

    {
      "mcpServers": {
        "starmux": {
          "type": "streamable-http",
          "url": "https://mcp.example.com/mcp",
          "headers": {
            "Authorization": "Bearer smx_YOUR_GENERATED_API_KEY"
          }
        }
      }
    }
  2. OAuth 2.0 + PKCE Browser Login (for ChatGPT Web): Acts as a standard OAuth 2.0 protected resource server with PKCE and session revocation (via self-hosted Keycloak). See Security & Authentication — OAuth 2.0.

2. Advanced: Multiple Instances, Separate Project Folders & stdio Multiplexing (-i)

(Optional) By default, Starmux runs a single default instance. If you want separate remote MCP endpoints on one computer—each with its own port, project directory / folder context, credentials, mounted stdio MCP servers, and Read-Only vs. Coding permission mode—pass -i <name>:

# Instance 1: Coding mode on port 18893 for repo-a
starmux up ~/work/repo-a -i work --code

# Instance 2: Strict Read-Only mode on an auto-assigned port for docs/blog folder
starmux up ~/personal/blog -i blog --read

starmux ls                      # List all instances with status, mode, port, and project folder
starmux config edit -i work     # Mount extra local stdio MCP servers (upstreams) or customize settings
starmux config apply -i work    # Hot-reload configuration changes
starmux down -i work            # Stop a specific instance

Security & Trust Boundary Note: Starmux's default Read-Only mode (--read) blocks write tools, shell execution, and Git mutations across the instance. In Coding mode (--code), terminal and file tools run with your OS account's permissions (the configured project directory sets the working context, not an OS chroot sandbox; an optional home-directory write sandbox is available on macOS). See Instances & Upstream Multiplexing and Security Model.


Everyday CLI Commands

starmux up --allow-lan  # Enable direct LAN / Tailscale access (0.0.0.0)
starmux up --local      # Restore loopback only (127.0.0.1)
starmux status          # Check health, endpoints, active permission mode, and recent tool activity
starmux up .            # Switch active project folder context to current directory
starmux auth            # View auth mode, create/revoke per-client API keys, and inspect OAuth sessions
starmux verify          # Run an end-to-end local MCP handshake, tool discovery, and read probe
starmux doctor          # Run environment, port lease, and configuration diagnostics
starmux dashboard       # Open the local Web Admin UI / Access Console to manage access & tool deny rules
starmux logs -f         # Stream live MCP gateway and tool invocation logs
starmux down            # Stop the gateway (alias: stop)

Tested AI Client Matrix

AI Client

Recommended Setup

Status

Detailed Guide

ChatGPT Web

Direct HTTPS or OpenAI Tunnel (+ OAuth 2.0)

✅ Tested

ChatGPT Web Setup

Claude App / Code

Chat Prompt (Claude Code) or Remote MCP Custom Connector (Claude App)

✅ Tested

AI Coding Agents · Claude App

WorkBuddy

Chat Prompt / Local / LAN / SSH / Caddy HTTPS (Mac $\rightarrow$ Linux / Jetson)

✅ Tested

WorkBuddy to Linux / Jetson Guide

Antigravity

Chat Prompt / Local / LAN / SSH / HTTPS

✅ Tested

AI Coding Agents Setup

Codex CLI / App

Chat Prompt / Tunnel or HTTPS + Bearer API Key

✅ Tested

Codex CLI Setup

Cursor

Chat Prompt / Local / LAN / SSH / HTTPS

✅ Tested

AI Coding Agents Setup

DSH-Harness / Kimi / Minimax / ZCode

Chat Prompt / Local / LAN / SSH / HTTPS

✅ Tested

AI Coding Agents Setup

Doubao (豆包)

Direct HTTPS or Tunnel

✅ Tested

Claude & Doubao Setup


Common Use Cases & FAQ

中文场景速览(一站式自托管远程 MCP 服务与网关): Starmux 将 Desktop Commander 风格的文件读写、代码搜索、Diff 编辑、交互式终端、进程管理与 Git 工具、stdio 转 Streamable HTTP 网关、多本地 stdio MCP 服务聚合、只读(Read-Only)与 Coding 权限切换、以及 API Key / OAuth 2.0 鉴权 一体化内置于单个守护进程中。无需手工拼装 DesktopCommanderMCP + supergateway + Caddy,即可让网页版 ChatGPT、Claude、豆包 或桌面端 WorkBuddy、Cursor、Codex、Antigravity 通过局域网/Tailscale 原生直连(--allow-lan)、Direct HTTPS(支持公网 IPv4/IPv6)、SSH 转发或内网穿透(NAT/CGNAT Tunnel)安全操作 Linux (x64/ARM64)、NVIDIA Jetson、macOS 与 Windows 上的本地文件与终端。


Native macOS App

Prefer a visual interface? The native SwiftUI menu bar App puts service health, Read-Only vs. Coding mode toggles, live MCP connection topology, and recent tool calls in one compact panel.

The App and CLI manage the same underlying instances. Quitting the App stops only instances started by the App; background instances started via CLI keep running.

Host Platform

Core & CLI (starmux)

Native Menu Bar App

macOS (Apple Silicon / Intel)

✅ Tested

🧪 Development Build (App Build Guide)

Linux (x64 / ARM64 / NVIDIA Jetson)

✅ Tested

—

Windows (x64)

✅ Tested

—


Documentation & Architecture Guides

Explore the Documentation Index by topic:

  • 📦 Installation, Platforms & Network Forwarding — Supported hosts (macOS, Linux, NVIDIA Jetson, Windows), everyday CLI commands, upgrades, source builds, and Caddy / Tunnel / SSH forwarding.

  • 🔒 Security, Access Control & Authentication — Global Read-Only vs. Coding permissions, trust boundaries, per-client Bearer API keys (starmux auth key), private local Admin UI, and self-hosted Keycloak OAuth 2.0 + PKCE.

  • 🤖 AI Client Configuration Guides — End-to-end setup (including 1-step Prompt Auto-Setup) for ChatGPT Web, Claude App / Code, WorkBuddy, Antigravity, Codex, Cursor, DSH-Harness, Kimi Code, Minimax Code, ZCode, and Doubao (豆包).

  • ⚙️ Multi-Instance & JSONC Configuration — Running multiple isolated instances (-i NAME), hot-reloading config.jsonc, mounting extra local stdio MCP servers (upstreams), and managing secrets.

License

Starmux original code is MIT Licensed. Desktop Commander is bundled as a pinned dependency and retains its own license and notices. Starmux is an independent open-source project and is not endorsed by Desktop Commander or AI client vendors.

Local management console

starmux dashboard opens the independent, owner-local control center, including when all MCP instances are stopped. It supports instance selection, lifecycle operations, saved configuration and JSONC editing, client credentials, OAuth, and bounded process logs. The interface offers English/Chinese and system/light/dark themes.

starmux dashboard                 # Start/reuse the local console and open it
starmux dashboard -i work          # Select an instance
starmux dashboard --no-open        # Print a private console login link
starmux dashboard status           # Inspect the console service
starmux dashboard stop             # Stop the console, leaving instances alone
starmux dashboard --token -i work  # Legacy per-instance owner token

The console binds only to loopback on its own port. Its login credential grants management of all local instances and is separate from MCP keys and legacy instance owner tokens. Private login links must not be shared with AI clients. Closing the browser does not stop the console; it does not start automatically at login. Saved configuration is applied separately, and concurrent edits produce a revision conflict instead of overwriting newer changes.

Available Tools

15 tools
get_configB
Read-only
                    Get the complete server configuration as JSON. Config includes fields for:
                    - blockedCommands (array of blocked shell commands)
                    - defaultShell (shell to use for commands)
                    - allowedDirectories (paths the server can access)
                    - fileReadLineLimit (max lines for read_file, default 1000)
                    - fileWriteLineLimit (max lines per write_file call, default 50)
                    - telemetryEnabled (boolean for telemetry opt-in/out)
                    - currentClient (information about the currently connected MCP client)
                    - clientHistory (history of all clients that have connected)
                    - version (version of the DesktopCommander)
                    - systemInfo (operating system and environment details)
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: origin.

get_file_infoA
Read-only
                    Retrieve detailed metadata about a file or directory including:
                    - size
                    - creation time
                    - last modified time
                    - permissions
                    - type
                    - lineCount (for text files)
                    - lastLine (zero-indexed number of last line, for text files)
                    - appendPosition (line number for appending, for text files)
                    - sheets (for Excel files - array of {name, rowCount, colCount})

                    Only works within allowed directories.
                    
                    Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: path (required).

get_more_search_resultsA
Read-only
                    Get more results from an active search with offset-based pagination.
                    
                    Supports partial result reading with:
                    - 'offset' (start result index, default: 0)
                      * Positive: Start from result N (0-based indexing)
                      * Negative: Read last N results from end (tail behavior)
                    - 'length' (max results to read, default: 100)
                      * Used with positive offsets for range reading
                      * Ignored when offset is negative (reads all requested tail results)
                    
                    Examples:
                    - offset: 0, length: 100     → First 100 results
                    - offset: 200, length: 50    → Results 200-249
                    - offset: -20                → Last 20 results
                    - offset: -5, length: 10     → Last 5 results (length ignored)
                    
                    Returns only results in the specified range, along with search status.
                    Works like read_process_output - call this repeatedly to get progressive
                    results from a search started with start_search.
                    
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: sessionId (required), length, offset.

get_recent_tool_callsA
Read-only
                    Get recent local tool call history with arguments and outputs.
                    Returns a chronological list of recent calls loaded from the local history file.
                    
                    Useful for:
                    - Onboarding new chats about work already done
                    - Recovering context after chat history loss
                    - Debugging tool call sequences
                    
                    Note: Does not track its own calls or track_ui_event.
                    History is persisted locally in tool-history.jsonl, keeps up to the last 1000
                    calls in memory, and trims older on-disk history. Stored outputs over 4 KiB
                    are replaced with an omission marker.
                    
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: since, toolName, maxResults.

get_usage_statsA
Read-only
                    Get usage statistics for debugging and analysis.
                    
                    Returns summary of tool usage, success/failure rates, and performance metrics.
                    
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: no named parameters.

health_checkB
Read-only

Starmux bridge connection, upstream availability and active mode check. Read-only blocks writes and arbitrary execution; Coding uses upstream tools with OS account permissions.

Inputs: no named parameters.

list_directoryA
Read-only
                    Get a detailed listing of all files and directories in a specified path.
                    
                    Returns a structured directory listing without starting a shell command.
                    Results distinguish between files and directories with [FILE] and [DIR] prefixes.
                    
                    Supports recursive listing with the 'depth' parameter (default: 2):
                    - depth=1: Only direct contents of the directory
                    - depth=2: Contents plus one level of subdirectories
                    - depth=3+: Multiple levels deep
                    
                    CONTEXT OVERFLOW PROTECTION:
                    - Top-level directory shows ALL items
                    - Nested directories are limited to 100 items maximum per directory
                    - When a nested directory has more than 100 items, you'll see a warning like:
                      [WARNING] node_modules: 500 items hidden (showing first 100 of 600 total)
                    - This prevents overwhelming the context with large directories like node_modules
                    
                    Results show full relative paths from the root directory being listed.
                    Example output with depth=2:
                    [DIR] src
                    [FILE] src/index.ts
                    [DIR] src/tools
                    [FILE] src/tools/filesystem.ts
                    
                    If a directory cannot be accessed, it will show [DENIED] instead.
                    If a path does not exist, it will show [NOT_FOUND] instead.
                    Only works within allowed directories.
                    
                    Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: path (required), depth, origin.

list_processesA
Read-only
                    List all running processes.
                    
                    Returns process information including PID, command name, CPU usage, and memory usage.
                    
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: no named parameters.

list_searchesA
Read-only
                    List all active searches.
                    
                    Shows search IDs, search types, patterns, status, and runtime.
                    Similar to list_sessions for terminal processes. Useful for managing
                    multiple concurrent searches.
                    
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: no named parameters.

list_sessionsA
Read-only
                    List all active terminal sessions.
                    
                    Shows session status including:
                    - PID: Process identifier  
                    - Blocked: Whether session is waiting for input
                    - Runtime: How long the session has been running
                    
                    DEBUGGING REPLs:
                    - "Blocked: true" often means REPL is waiting for input
                    - Use this to verify sessions are running before sending input
                    - Long runtime with blocked status may indicate stuck process
                    
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: no named parameters.

read_fileA
Read-only
                    Read contents from files and URLs.
                    Read PDF files and extract content as markdown and images.
                    
                    Suitable for reading authorized local files directly without starting a shell command.
                    
                    Supports partial file reading with:
                    - 'offset' (start line, default: 0)
                      * Positive: Start from line N (0-based indexing)
                      * Negative: Read last N lines from end (tail behavior)
                    - 'length' (max lines to read, default: configurable via 'fileReadLineLimit' setting, initially 1000)
                      * Used with positive offsets for range reading
                      * Ignored when offset is negative (reads all requested tail lines)
                    
                    Examples:
                    - offset: 0, length: 10     → First 10 lines
                    - offset: 100, length: 5    → Lines 100-104
                    - offset: -20               → Last 20 lines  
                    - offset: -5, length: 10    → Last 5 lines (length ignored)
                    
                    Performance optimizations:
                    - Large files with negative offsets use reverse reading for efficiency
                    - Large files with deep positive offsets use byte estimation
                    - Small files use fast readline streaming
                    
                    When reading from the file system, only works within allowed directories.
                    Can fetch content from URLs when isUrl parameter is set to true
                    (URLs are always read in full regardless of offset/length).
                    
                    FORMAT HANDLING (by extension):
                    - Text: Uses offset/length for line-based pagination
                    - Excel (.xlsx, .xls, .xlsm): Returns JSON 2D array
                      * sheet: "Sheet1" (name) or "0" (index as string, 0-based)
                      * range uses FROM:TO format (e.g., "A1:D100", "C1:C1", "B2:B50")
                      * offset/length work as row pagination (optional fallback)
                    - Images (PNG, JPEG, GIF, WebP): Base64 encoded viewable content
                    - PDF: Extracts text content as markdown with page structure
                      * offset/length work as page pagination (0-based)
                      * Includes embedded images when available
                    - DOCX (.docx): Two modes depending on parameters:
                      * DEFAULT (no offset/length): Returns a text-bearing outline — shows paragraphs with text,
                        tables with cell content, styles, image refs. Skips shapes/drawings/SVG noise.
                        Each element shows its body index [0], [1], etc.
                      * WITH offset/length: Returns raw pretty-printed XML with line pagination.
                        Use this to drill into specific sections or see the actual XML for editing.
                      * Raw DOCX XML output is compatible with edit_block's XML find/replace mode using
                        XML fragments copied from the read output.
                      * Raw XML mode requires a non-zero offset (offset=1 starts from line 1).
                        offset=0 returns the outline regardless of length.
                      * Bulk transformations can be performed programmatically against the DOCX archive
                        when the task requires changes across many XML text nodes.

                    Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: path (required), isUrl, range, sheet, +4 more.

read_multiple_filesA
Read-only
                    Read the contents of multiple files simultaneously.
                    
                    Each file's content is returned with its path as a reference.
                    Handles text files normally and renders images as viewable content.
                    Recognized image types: PNG, JPEG, GIF, WebP.
                    
                    Failed reads for individual files won't stop the entire operation.
                    Only works within allowed directories.
                    
                    Absolute paths are the most reliable because they do not depend on the current working directory. Paths are automatically normalized regardless of slash direction. Relative paths depend on the current working directory, and tilde paths (~/...) may not resolve in every context. Absolute paths are generally the most reliable.
                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: paths (required).

read_process_outputA
Read-only
                    Read output from a running process with file-like pagination support.
                    
                    Supports partial output reading with offset and length parameters (like read_file):
                    - 'offset' (start line, default: 0)
                      * offset=0: Read NEW output since last read (default, like old behavior)
                      * Positive: Read from absolute line position
                      * Negative: Read last N lines from end (tail behavior)
                    - 'length' (max lines to read, default: configurable via 'fileReadLineLimit' setting)
                    
                    Examples:
                    - offset: 0, length: 100     → First 100 NEW lines since last read
                    - offset: 0                  → All new lines (respects config limit)
                    - offset: 500, length: 50    → Lines 500-549 (absolute position)
                    - offset: -20                → Last 20 lines (tail)
                    - offset: -50, length: 10    → Start 50 from end, read 10 lines
                    
                    OUTPUT PROTECTION:
                    - Uses same fileReadLineLimit as read_file (default: 1000 lines)
                    - Returns status like: [Reading 100 lines from line 0 (total: 5000 lines, 4900 remaining)]
                    - Prevents context overflow from verbose processes
                    
                    SMART FEATURES:
                    - For offset=0, waits up to timeout_ms for new output to arrive
                    - Detects REPL prompts and process completion
                    - Shows process state (waiting for input, finished, etc.)
                    
                    DETECTION STATES:
                    Process waiting for input (ready for interact_with_process)
                    Process finished execution
                    Timeout reached (may still be running)

                    This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.

Inputs: pid (required), length, offset, timeout_ms, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have clearly distinct targets: file reading, directory listing, search lifecycle, process inspection, and config/telemetry each occupy their own niche. Minor overlap exists between list_directory and start_search(searchType="files"), and between list_sessions and list_processes, plus get_recent_tool_calls vs get_usage_stats, but descriptions make the boundaries workable.

    Naming Consistency5/5

    Nearly every tool follows a clean verb_noun snake_case pattern (read_file, list_directory, start_search, get_more_search_results, stop_search, get_file_info). The only deviation is health_check, which is a widely recognized idiom and does not break readability.

    Tool Count5/5

    15 tools is within the well-scoped range for a filesystem/terminal commander surface. The search family (start/get_more/stop/list) is grouped logically and each tool earns its place rather than bloating the surface.

    Completeness3/5

    The read/search side is thorough (files, multiple files, URLs, PDF/Excel/DOCX, metadata, paginated search lifecycle), but the write and execution side is entirely absent — no write_file, edit_block, create_directory, execute_command, start_process, interact_with_process, or kill_process. This leaves dead ends: you can list sessions and read process output but cannot start, interact with, or terminate a process, which is a notable gap for a terminal-oriented server (even if read-only mode is intentional).

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Turns any Linux server into an AI-agent-accessible machine over HTTPS, allowing MCP clients like ChatGPT, Claude, and Grok to securely control files, run shell commands, inspect system state, query SQLite, and work with git behind a bearer token.
      74 npm
      4
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes a governed suite of 38 tools over a single OAuth-gated MCP endpoint, letting web-based AI clients such as Claude, ChatGPT, and Grok read and edit files, run whitelisted shell commands, search, query SQLite, use Git, automate browsers and DevTools, manage background tasks, reach localhost services, and control the clipboard, notifications, ports, and Postman. This turns remote AI chats into secure operators of a local machine without granting unrestricted shell access.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Connects web-based AI chat clients such as Claude, ChatGPT, and Grok to a local machine through a single OAuth-gated MCP endpoint so they can browse, read, write, and edit files, run whitelisted shell commands, search content, use Git, query SQLite, drive browsers and DevTools, and manage background tasks, ports, and clipboard. It also exposes localhost and LAN services via a protected HTTP client, letting remote or mobile clients debug and operate local projects without granting unrestricted shell access.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables web-based AI clients like Claude, ChatGPT, and Grok to securely operate a local machine through OAuth-gated MCP tools covering files, shell, Git, databases, browser automation, and background tasks.
      MIT