MCP Server Shell

🚀 Shell MCP Server

A Model Context Protocol (MCP) server that provides shell command execution capabilities. This server enables large language models to securely execute shell commands and receive their outputs.

🚀 Quick Start

✨ Features

• Available Tools:
  • execute_command: Executes a shell command and returns its output.
    • Required Parameters:
      • command (string): The shell command to be executed.
    • Return Content:
      • command: The executed command.
      • output: The combined stdout and stderr outputs.
      • return_code: The return code of the command execution.

📦 Installation

• Using uv (Recommended): When using uv, no specific installation is required. We will directly use uvx to run mcp-server-shell.
• Using pip: Alternatively, you can install mcp-server-shell via pip:

  pip install mcp-server-shell
  

  After installation, you can run it as a script:

  python -m mcp_server_shell
  

Configuration Guide

• Configuration for Claude.app: Add the following to your Claude settings:
  Using uvx

  ```json "mcpServers": { "shell": { "command": "uvx", "args": ["mcp-server-shell"] } } ```
  Using pip Installation

  ```json "mcpServers": { "shell": { "command": "python", "args": ["-m", "mcp_server_shell"] } } ```
• Configuration for Zed: Add the following to your Zed settings.json:
  Using uvx

  ```json "context_servers": { "mcp-server-shell": { "command": "uvx", "args": ["mcp-server-shell"] } }, ```
  Using pip Installation

  ```json "context_servers": { "mcp-server-shell": { "command": "python", "args": ["-m", "mcp_server_shell"] } }, ```

💻 Usage Examples

Basic Usage

Execute a shell command:

{
  "name": "execute_command",
  "arguments": {
    "command": "ls -la"
  }
}

Response:

{
  "command": "ls -la",
  "output": "total 24\ndrwxr-xr-x  5 user  group   160 Jan  1 12:00 .\ndrwxr-xr-x  3 user  group    96 Jan  1 12:00 ..",
  "return_code": 0
}

🔧 Technical Details

• Debugging Method: You can use the MCP inspector to debug the server. For uvx installation:

  npx @modelcontextprotocol/inspector uvx mcp-server-shell
  

  Or if you installed or developed this package in a specific directory:

  cd path/to/servers/src/shell
  npx @modelcontextprotocol/inspector uv run mcp-server-shell
  

• Example Questions (for Claude):
  1. "What files are in the current directory?"
  2. "Show the contents of the README.md file."
  3. "What is the current system date?"
  4. "Check if Python is installed and show its version."

⚠️ Important Note

This server directly executes shell commands locally. Please ensure that the input commands are trustworthy to prevent potential security risks.

🤝 Contribution Guide

If you want to contribute, please refer to the project documentation or contact the maintainers.

📄 License

[Add license information here]