mcp-shell-server

Overview Schema Source Related Servers Discussions Admin

shell_execute

Execute allowed shell commands like wc, grep, cat, ls, and pwd on the server host with configurable timeout and stdin support, enabling controlled remote command execution.

Instructions

Execute an allowed command as an argv array on the MCP server host. Allowed commands run with the server process's OS authority; the allowlist controls executable names, not what an allowed program does. Allowed commands: wc, grep, cat, ls, pwd Allowed patterns: Default timeout: 30s; maximum timeout: 300s; output cap: 1048576 bytes

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "command": "<command>"
    },
    "name": "shell_execute"
  }
}

Input Schema

Name	Required	Description
`stdin`	No	Input to be passed to the command via stdin
`command`	Yes	Command and its arguments as array
`timeout`	No	Maximum execution time in seconds; clamped to server maximum
`directory`	No	Optional working directory. Omit to use the MCP server process current working directory; relative paths are resolved from that same server process CWD.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.1.0Jun 17, 2026

changedInput schema / properties / directory / description

Previous value: -"Absolute path to a working directory where the command will be executed"New value: +"Optional working directory. Omit to use the MCP server process current working directory; relative paths are resolved from that same server process CWD."

changedInput schema / properties / timeout / description

Previous value: -"Maximum execution time in seconds"New value: +"Maximum execution time in seconds; clamped to server maximum"

changedInput schema / properties / timeout / minimum
```
Previous value: -0New value: +1
```

changedInput schema / required

Previous value: -[
-  "command",
-  "directory"
-]New value: +[
+  "command"
+]

First observedAug 18, 2025

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses OS authority, warns that the allowlist controls executable names rather than program behavior, and gives timeout and output-cap limits. It does not describe return values such as stdout, stderr, exit code, or truncation signaling, which is a meaningful gap for a command execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loads the core behavior and security warning. The empty 'Allowed patterns:' line is a small structural blemish that detracts slightly from an otherwise efficient definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a security-sensitive command execution tool with no annotations and no output schema, the definition covers authority, allowlist limits, timeouts, and output cap. It omits return semantics (stdout/stderr/exit code/truncation behavior) and leaves 'Allowed patterns' blank, so it is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by specifying the executable allowlist for the command parameter and the default/max timeout values; however, the empty 'Allowed patterns:' line leaves part of the stated constraint incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: execute an allowed command as an argv array on the MCP server host. It also names the allowlist scope and the commands available, so an agent can immediately tell what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly limits usage to the allowlisted commands (wc, grep, cat, ls, pwd) and notes that commands run with the server process's OS authority. It does not give explicit when-not-to-use guidance, but the allowlist provides strong usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools

shell_executeA