Skip to main content
Glama
enesjakozh
hdresearch

Shell MCP Server

by hdresearch
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

Shell MCP Server

A Node.js implementation of the Model Context Protocol (MCP) that provides secure shell command execution capabilities. This server allows AI models to execute shell commands in a controlled environment with built-in security measures. Easily integrates with Claude Desktop for connecting Claude with your shell.

Features

  • MCP-compliant server implementation

  • Secure command execution with blacklist protection

  • Command existence validation

  • Standard I/O based transport

  • Error handling and graceful shutdown

Related MCP server: MCP Shell Server

Installation

Run npx mcp-shell.

To add it to Claude Desktop, run npx mcp-shell config. Or add npx -y mcp-shell to your config manually.

Start (or restart) Claude Desktop and you should see the MCP tool listed on the landing page.

Security Features

The server implements several security measures:

  1. Command Blacklisting

    • Prevents execution of dangerous system commands

    • Blocks access to critical system modifications

    • Protects against file system destruction

    • Prevents privilege escalation

  2. Command Validation

    • Verifies command existence before execution

    • Validates against the blacklist

    • Returns clear error messages for invalid commands

Available Tools

The server provides one tool:

run_command

Executes a shell command and returns its output.

Input Schema:

{
  "type": "object",
  "properties": {
    "command": { "type": "string" }
  }
}

Response:

  • Success: Command output as plain text

  • Error: Error message as plain text

Blacklisted Commands

The following command categories are blocked for security:

  • File System Destruction Commands (rm, rmdir, del)

  • Disk/Filesystem Commands (format, mkfs, dd)

  • Permission/Ownership Commands (chmod, chown)

  • Privilege Escalation Commands (sudo, su)

  • Code Execution Commands (exec, eval)

  • System Communication Commands (write, wall)

  • System Control Commands (shutdown, reboot, init)

Error Handling

The server includes comprehensive error handling:

  • Command not found errors

  • Blacklisted command errors

  • Execution errors

  • MCP protocol errors

  • Graceful shutdown on SIGINT

Implementation Details

The server is built using:

  • Model Context Protocol SDK

  • StdioServerTransport for communication

  • execa for command execution

  • command-exists for command validation

Development

To modify the security settings, you can:

  1. Edit the BLACKLISTED_COMMANDS set to adjust blocked commands

  2. Modify the validateCommand function to add additional validation rules

  3. Enhance the command parsing logic in the CallToolRequestSchema handler

Available Tools

1 tool
run_commandC

Run a shell command

ParametersJSON Schema
NameRequiredDescriptionDefault
commandNo

TDQS

C2.6/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden but only states the action without disclosing behavioral traits. It doesn't cover critical aspects like whether the command runs locally or remotely, if it requires elevated privileges, potential side effects (e.g., file modifications), error handling, or output format. This leaves significant uncertainty for safe and effective use.

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

Conciseness5/5

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

The description is extremely concise with just three words, front-loaded and zero waste. It efficiently conveys the core action without unnecessary elaboration, making it easy to parse quickly. However, this conciseness comes at the cost of completeness, as noted in other dimensions.

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

Completeness2/5

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

Given the complexity of running shell commands (which can be high-risk with mutations and side effects), no annotations, no output schema, and low parameter coverage, the description is incomplete. It lacks essential context such as execution environment, security implications, error responses, and usage scenarios, making it inadequate for safe agent operation.

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

Parameters2/5

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

The input schema has 1 parameter with 0% description coverage, and the description adds no meaning beyond the schema. It doesn't explain what the 'command' parameter should contain (e.g., syntax, examples, allowed commands) or any constraints. Since schema coverage is low, the description fails to compensate, leaving the parameter poorly documented.

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

Purpose3/5

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

The description 'Run a shell command' clearly states the action (run) and target (shell command), providing a basic understanding of purpose. However, it lacks specificity about what kind of shell command or execution environment, making it somewhat vague. Since there are no sibling tools, differentiation isn't required, but the description could be more detailed.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool, such as for administrative tasks, automation, or debugging. It doesn't mention prerequisites like permissions, security considerations, or alternatives, leaving the agent with no context for decision-making. With no sibling tools, this is less critical but still a gap.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.0.0
    • First observedrun_command
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.9/5.0
Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool 'run_command' has a clear and distinct purpose that cannot be confused with any other tool in this set.

Naming Consistency5/5

The naming is perfectly consistent as there is only one tool. It follows a clear verb_noun pattern ('run_command'), and with no other tools to compare against, there is no inconsistency in naming conventions.

Tool Count2/5

A single tool is too few for a server named 'Shell MCP Server', which implies broader shell-related functionality. This minimal set feels thin and under-scoped, as it only covers basic command execution without supporting common shell operations like listing files, checking processes, or managing environment variables.

Completeness2/5

The tool set is severely incomplete for a shell server. While 'run_command' covers arbitrary command execution, it lacks tools for specific shell tasks (e.g., file operations, process management, directory navigation), leaving significant gaps that will likely cause agent failures when trying to perform common shell workflows.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Shell MCP Server

    odysseus0
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that allows LLMs to execute shell commands and receive their output in a controlled manner.
    7
    MIT

  • MCP Shell Server

    JMReader
    F
    license
    Not graded
    quality
    D
    maintenance
    A secure interface that enables language models to execute shell commands on the host operating system through the Model Context Protocol.
    1
    -

  • SSH MCP Server

    vilasone455
    F
    license
    A
    quality
    D
    maintenance
    A local Model Context Protocol server that allows LLMs to securely execute shell commands on remote Linux and Windows systems via SSH connections.
    6
    17
    2
    -

  • Simple Subprocess MCP Server

    yonaka15
    F
    license
    B
    quality
    D
    maintenance
    A Model Context Protocol server that enables LLM applications to safely execute shell commands with error handling and timeout settings.
    1
    -

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hdresearch/mcp-shell'

If you have feedback or need assistance with the MCP directory API, please join our Discord server