home / mcp / shell mcp server

Shell MCP Server

Executes shell commands via MCP clients and returns combined output plus exit codes.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "odysseus0-mcp-server-shell": {
      "command": "uvx",
      "args": [
        "mcp-server-shell"
      ]
    }
  }
}

This MCP server lets you execute shell commands in a controlled way from your MCP-enabled client. It enables you to run shell commands and receive their combined output and exit status, making it useful for automating tasks or querying the local system within a constrained, introspective environment.

How to use

To use the Shell MCP Server from your MCP client, call the execute_command tool with the shell command you want to run. The server will return the command you issued, the combined stdout and stderr output, and the command’s return code. Use this to perform routine checks, gather directory listings, or run simple scripts without leaving the MCP workflow.

How to install

Prerequisites vary by your chosen run method. You can either run the server directly with the uv tool or install it via Python’s package manager.

# Option 1: Run with uvx (recommended)
# No separate installation needed beyond having uvx available on your system
uvx mcp-server-shell

# Option 2: Install via pip and run as a module
pip install mcp-server-shell
python -m mcp_server_shell

Additional configuration and usage details

You can configure how the server is invoked in two common environments. Use the uvx-based invocation for a lightweight setup, or run the Python package if you prefer a Python-based workflow.

Configuration forClaude.app and Zed

Configure the MCP client to connect to the shell server using the following command patterns. When using uvx, the server is started with the mcp-server-shell executable. When using Python, start it with the Python module.

Security considerations

Remember that executing shell commands can affect your system. Use strict access control and validate the commands you allow through the MCP interface to minimize risk.

Examples of typical use cases

Examples include listing files, checking system information, and querying environment details through the execute_command tool. For instance, you can request a directory listing to confirm contents or verify the presence and version of a tool by running a simple command.

Available tools

execute_command

Execute a shell command and return its output, plus the command string and return code.