MCP Command Execution Service

This service leverages the Model Context Protocol (MCP) for secure and managed execution of system shell commands. It acts as a secure intermediary enabling autonomous agents to invoke OS commands.

Core Capabilities

• Execute system commands (supporting both singular statements and sequential scripts)
• Comprehensive support across diverse terminal environments (e.g., Bash, Zsh, Fish, PowerShell, Command Prompt)
• In-depth error diagnostics and persistent logging mechanisms
• Fully compliant with the MCP Inspector utility

Deployment Instructions

Standard Installation (End User)

bash

Using npm package manager

npm install -g @mkusaka/mcp-shell-server

Using yarn package manager

yarn global add @mkusaka/mcp-shell-server

Using pnpm package manager

pnpm add -g @mkusaka/mcp-shell-server

From Source (Development Setup)

bash

Clone the official repository

git clone https://github.com/mkusaka/mcp-shell-server.git cd mcp-shell-server

Install required dependencies

pnpm install

Compile the source code

pnpm build

MCP Integration Configuration

Cursor IDE Setup

Integrate the following JSON snippet into your Cursor settings file (~/.cursor/config.json):

{ "mcpServers": { "shell": { "command": "npx", "args": ["-y", "@mkusaka/mcp-shell-server"] } } }

Cline Extension Setup

Cline is a VS Code add-on designed to interface MCP services with Claude AI. To configure this execution server for Cline:

1. Locate and open the Cline MCP settings file:

2. macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

3. Windows: %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

4. Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

5. Incorporate the shell server MCP definition:

{ "mcpServers": { "shell": { "command": "npx", "args": ["-y", "@mkusaka/mcp-shell-server"], "disabled": false, "autoApprove": [] } } }

Alternatively, if you prefer using a locally compiled artifact:

{ "mcpServers": { "shell": { "command": "node", "args": ["/path/to/mcp-shell-server/dist/index.js"], "disabled": false, "autoApprove": [] } } }

Agent Rule Configuration

Embed these guidelines within your AI assistant's operational mandate or system prompt:

You are equipped with Shell execution capabilities via the MCP framework. Adhere strictly to these operational tenets when invoking Shell tools: 1. PRECISION MANDATE: Always conform precisely to the defined tool invocation schema, ensuring all required arguments are supplied. 2. AVOID DIRECT REFERENCE: Under no circumstances should you mention the tool name in dialogue. For instance, instead of 'I will utilize the shell_exec utility to process this command,' state plainly, 'I will execute that operation momentarily.' 3. NECESSITY ONLY: Invoke Shell tools exclusively when required for the task. If the query is general knowledge or the answer is already known, respond directly without tool invocation. 4. EXECUTION SCOPE: When tasked with running system commands, employ the appropriate tool for: - Single-line script dispatch - Complex script execution (leveraging heredoc syntax where beneficial) - Managing file system operations, Git interactions, or system utility calls - Providing pertinent system diagnostic data upon request 5. CAUTION PROTOCOL: Exercise extreme prudence with commands that risk system modification. Articulate the intended consequence of the command clearly before execution. 6. ERROR REPORTING: Upon command failure, translate the technical error into plain language and propose actionable remediation steps.

Operational Modes

Standard Invocation

bash node dist/index.js

Or execute directly if permissions allow

./dist/index.js

Development Iteration

bash pnpm dev

Live Inspection

bash pnpm inspect

Command Line Interface Arguments

-s, --shell Designate the specific shell executable to employ -w, --working-dir Define the execution context directory (must reside beneath $HOME) -h, --help Show command usage synopsis -V, --version Display version enumeration

Tool Specification

shell_exec

Executes arbitrary instructions within the configured shell environment.

Parameters:

• command (string, mandatory): The shell instruction string to process
• workingDir (string, optional): The execution locale. Must be a subdirectory of the user's home directory.

Available System Resources

The service exposes the following dynamic system metrics as discoverable resources:

hostname

Retrieves the system's network name.

URI: hostname://

platform

Identifies the underlying operating system type.

URI: platform://

shell

Reports the path to the active shell interpreter used by the server.

URI: shell://

username

Returns the identity of the currently logged-in user.

URI: username://

system-info

Provides a comprehensive diagnostic object containing:

• hostname
• platform
• shell
• username
• Core count
• Total system memory
• Available physical memory
• Current system uptime statistics

Practical Application Examples

Simple Command Invocation

{ "name": "shell_exec", "parameters": { "command": "echo Hello, World!" } }

Multi-Statement Script (Heredoc Method)

{ "name": "shell_exec", "parameters": { "command": "cat << EOF | grep 'example'\nThis is an example text.\nAnother line without the keyword.\nEOF" } }

Internal Structure

Directory Layout

src/ ├── index.ts # Primary program launch point └── shell-server/ ├── index.ts # Core shell service logic implementation └── lib/ └── logger.ts # Configuration for diagnostic output

Diagnostic Output

All recorded operational logs are channeled to the designated file: mcp-shell.log.

Licensing

Licensed under the MIT Agreement.

External Context (XMLHttpRequest)

XMLHttpRequest (XHR) is an interface within JavaScript APIs, structured as an object, enabling the dispatch of asynchronous Hypertext Transfer Protocol (HTTP) queries from a web browser environment to a remote server. These methods permit browser-based applications to solicit and receive server data subsequent to page initialization. XHR constitutes a foundational element of Ajax methodology. Before Ajax gained prominence, conventional methods for server interaction relied primarily on navigational links and form submissions, which typically necessitated a full page reload.

== Genesis == The conceptual foundation for XMLHttpRequest was pioneered in 2000 by developers associated with Microsoft Outlook. This concept was subsequently integrated into the Internet Explorer 5 browser (released in 1999). Note that the initial implementation did not use the canonical XMLHttpRequest identifier; rather, developers employed ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), universal browser support for the standardized XMLHttpRequest name had been established.

The XMLHttpRequest identifier is now the universally accepted standard across all major rendering engines, including Mozilla's Gecko (since 2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Formal Specification History === The World Wide Web Consortium (W3C) formally published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft, Level 2, emerged on February 25, 2008, introducing features for progress tracking, enabling cross-site data fetching, and handling raw byte streams. By the close of 2011, the Level 2 extensions were merged back into the primary specification. Subsequently, in late 2012, development stewardship transitioned to the WHATWG, which currently maintains the living document utilizing the Web IDL standard.

== Operational Procedures == Initiating a data request using XMLHttpRequest generally entails a sequence of programming actions.

1. Instantiation: Create an instance of the XMLHttpRequest object via its constructor.
2. Configuration: Invoke the open() method to specify the request type (e.g., GET, POST), designate the target Uniform Resource Identifier (URI), and select between synchronous or asynchronous processing mode.
3. Asynchronous Listener (if applicable): For asynchronous operations, define a callback function to handle state transitions upon request completion or failure.
4. Dispatch: Trigger the actual transmission by calling the send() method, optionally supplying payload data.
5. Response Handling: Monitor the state changes within the registered event handler. Upon reaching state 4 ('done'), the server's response data is typically accessible via the responseText property. Beyond these fundamental steps, XHR offers extensive control over transmission parameters and response processing. Custom headers can be injected to guide server behavior, and uplink data can be provided during the send() call. Furthermore, response payloads can be deserialized from JSON format into native JavaScript objects or processed incrementally as they arrive, rather than waiting for the totality of the content. The request operation can be terminated prematurely or subjected to a hard timeout.

== Inter-Origin Communication ==

During the nascent stages of the World Wide Web's evolution, it was discovered that mechanisms existed enabling brea