Starmux
Starmux is a self-hosted remote MCP gateway for inspecting files, directories, searches, processes, sessions, configuration, and health, with write/edit/terminal/Git tools available in Coding mode.
Read local files, URLs, PDFs, images, Excel, and DOCX content with line/page/range pagination.
Read multiple files at once and list directory contents recursively with depth limits.
Search files by name or search inside file contents using regex or literal matching; paginate, stop, and list active searches.
Retrieve file metadata such as size, timestamps, permissions, line count, and Excel sheet info.
Inspect running processes and terminal sessions, and read process output with pagination.
View server configuration, usage statistics, recent tool-call history, and health/upstream/mode status.
In Coding mode, use filesystem writes/edits, shell/PTY terminal sessions, background process management, and Git workflows; default Read-only mode blocks writes and execution.
Connect AI clients remotely via Streamable HTTP
/mcp, LAN, HTTPS, tunnels, API keys, or OAuth.
Provides built-in Git tooling via the daemon's coding mode, letting AI clients run Git workflows against a project directory on the host alongside filesystem edits and terminal sessions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Starmux list the files in /home/ubuntu/projects and show recent errors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 HTTPBridge & Multi-Server Aggregator: Exposes a nativeStreamable HTTP(/mcp) endpoint directly and can multiplex your own extra localstdioMCP servers (upstreams) behind the same port—no separatesupergatewayormcp-proxywrapper 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 ( | Pure MCP Gateways ( | SSH MCP Bridges ( | 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 | ✅ Built-in | ⚠️ Requires transport adapter | ✅ Built-in | ❌ Local | ✅ 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 | ✅ Via vendor cloud |
Headless Linux | ✅ Single-command CLI ( | ⚠️ 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 ( | ❌ 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 | ✅ 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 --codeStarmux 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) |
|
|
A2. Public Domain / Cloud AI Requiring HTTPS | Keep |
|
B. Behind NAT / CGNAT | Keep | Your tunnel's HTTPS URL ending in |
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:18893Caddy 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:18893No 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 |
|
URL |
|
Authentication |
|
or, Option 3 — Manually paste into mcp.json
Same-computer connection (or when using local
ssh -Lport 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.1across 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
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
Authorizationheader to your client'smcp.json:{ "mcpServers": { "starmux": { "type": "streamable-http", "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer smx_YOUR_GENERATED_API_KEY" } } } }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 instanceSecurity & 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 | |
Claude App / Code | Chat Prompt ( | ✅ Tested | |
WorkBuddy | Chat Prompt / Local / LAN / SSH / Caddy HTTPS (Mac $\rightarrow$ Linux / Jetson) | ✅ Tested | |
Antigravity | Chat Prompt / Local / LAN / SSH / HTTPS | ✅ Tested | |
Codex CLI / App | Chat Prompt / Tunnel or HTTPS + Bearer API Key | ✅ Tested | |
Cursor | Chat Prompt / Local / LAN / SSH / HTTPS | ✅ Tested | |
DSH-Harness / Kimi / Minimax / ZCode | Chat Prompt / Local / LAN / SSH / HTTPS | ✅ Tested | |
Doubao (豆包) | Direct HTTPS or Tunnel | ✅ Tested |
Common Use Cases & FAQ
How can ChatGPT access files and terminal tools on my local computer? Run
starmux uplocally and expose127.0.0.1:18893/mcpvia OpenAI Secure MCP Tunnel or Direct HTTPS so ChatGPT Web can inspect folders or run tools without manual file uploads.How can WorkBuddy on Mac/Windows operate a headless Linux server or NVIDIA Jetson remotely? Install Starmux on the Linux
x64/ARM64or NVIDIA Jetson Orin host, expose/mcpdirectly with--allow-lanor over HTTPS with Caddy, and add"type": "streamable-http"in WorkBuddy—no Linux desktop app required.Is there a self-hosted, open-source alternative to the hosted Remote Desktop Commander service? Yes. Starmux bundles the open-source Desktop Commander tool engine with a built-in Streamable HTTP server, read-only controls, and self-hosted auth so your tools execute without a third-party cloud relay.
How do I aggregate multiple local
stdioMCP servers behind one Streamable HTTP endpoint? Configureupstreamsin your Starmux instance (starmux config edit) to multiplex extrastdioMCP servers alongside built-in filesystem/terminal tools on a single port.How do I connect a cloud AI client to an MCP server behind NAT / CGNAT? Compare outbound tunnels (OpenAI Tunnel, Cloudflare Tunnel,
frp,rathole), Direct IPv6/IPv4 HTTPS with Caddy, and SSH port forwarding.How can I secure a self-hosted remote MCP server with OAuth 2.0 or revocable API keys? Use
starmux auth keyfor per-client Bearer tokens or configure Keycloak OAuth 2.0 + PKCE for browser-based AI connectors.
中文场景速览(一站式自托管远程 MCP 服务与网关): Starmux 将 Desktop Commander 风格的文件读写、代码搜索、Diff 编辑、交互式终端、进程管理与 Git 工具、
stdio转Streamable HTTP网关、多本地stdioMCP 服务聚合、只读(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 ( | Native Menu Bar App |
macOS ( | ✅ Tested | 🧪 Development Build (App Build Guide) |
Linux ( | ✅ Tested | — |
Windows ( | ✅ 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-reloadingconfig.jsonc, mounting extra localstdioMCP 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 tokenThe 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 toolsget_configBRead-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_infoARead-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_resultsARead-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_callsARead-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_statsARead-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_checkBRead-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_directoryARead-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_processesARead-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_searchesARead-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_sessionsARead-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_fileARead-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_filesARead-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_outputARead-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.
start_searchARead-only
Start a streaming search that can return results progressively.
SEARCH STRATEGY GUIDE:
Choose the right search type based on what the user is looking for:
USE searchType="files" WHEN:
- User asks for specific files: "find package.json", "locate config files"
- Pattern looks like a filename: "*.js", "README.md", "test-*.tsx"
- User wants to find files by name/extension: "all TypeScript files", "Python scripts"
- Looking for configuration/setup files: ".env", "dockerfile", "tsconfig.json"
USE searchType="content" WHEN:
- User asks about code/logic: "authentication logic", "error handling", "API calls"
- Looking for functions/variables: "getUserData function", "useState hook"
- Searching for text/comments: "TODO items", "FIXME comments", "documentation"
- Finding patterns in code: "console.log statements", "import statements"
- User describes functionality: "components that handle login", "files with database queries"
AMBIGUOUS SEARCHES:
Queries that could refer to either filenames or file contents can be covered with two
searches: one with searchType="files" and one with searchType="content".
Example: "find authentication stuff" can pair a filename search for "auth" with a
content search for "authentication".
SEARCH TYPES:
- searchType="files": Find files by name (pattern matches file names)
- searchType="content": Search inside files for text patterns
PATTERN MATCHING MODES:
- Default (literalSearch=false): Patterns are treated as regular expressions
- Literal (literalSearch=true): Patterns are treated as exact strings
literalSearch=true is useful for code patterns with special characters:
- Function calls with parentheses and quotes
- Array access with brackets
- Object methods with dots and parentheses
- File paths with backslashes
- Any pattern containing: . * + ? ^ $ { } [ ] | \ ( )
IMPORTANT PARAMETERS:
- pattern: What to search for (file names OR content text)
- literalSearch: Use exact string matching instead of regex (default: false)
- filePattern: Optional filter to limit search to specific file types (e.g., "*.js", "package.json")
- ignoreCase: Case-insensitive search (default: true). Works for both file names and content.
- earlyTermination: Stop search early when exact filename match is found (optional: defaults to true for file searches, false for content searches)
DECISION EXAMPLES:
- "find package.json" → searchType="files", pattern="package.json" (specific file)
- "find authentication components" → searchType="content", pattern="authentication" (looking for functionality)
- "locate all React components" → searchType="files", pattern="*.tsx" or "*.jsx" (file pattern)
- "find TODO comments" → searchType="content", pattern="TODO" (text in files)
- "show me login files" → AMBIGUOUS → run both: files with "login" AND content with "login"
- "find config" → AMBIGUOUS → run both: config files AND files containing config code
COMPREHENSIVE SEARCH EXAMPLES:
- Find package.json files: searchType="files", pattern="package.json"
- Find all JS files: searchType="files", pattern="*.js"
- Search for TODO in code: searchType="content", pattern="TODO", filePattern="*.js|*.ts"
- Search for exact code: searchType="content", pattern="toast.error('test')", literalSearch=true
- Ambiguous request "find auth stuff": Run two searches:
1. searchType="files", pattern="auth"
2. searchType="content", pattern="authentication"
Ambiguous requests can combine file-name and content searches for broader coverage.
This tool starts a background search process and returns immediately with a session ID.
Results are available through get_more_search_results, and stop_search can end the search early.
Perfect for large directories where you want to see results immediately and
have the option to cancel if the search takes too long or you find what you need.
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), pattern (required), origin, ignoreCase, +8 more.
stop_searchA
Stop an active search.
Stops the background search process gracefully. Use this when you've found
what you need or if a search is taking too long. Similar to force_terminate
for terminal processes.
The search will still be available for reading final results until it's
automatically cleaned up after 5 minutes.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.Inputs: sessionId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceTurns 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 npm4MIT
- FlicenseNot gradedqualityAmaintenanceExposes 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.-
- FlicenseNot gradedqualityAmaintenanceConnects 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.-
- AlicenseNot gradedqualityAmaintenanceEnables 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