Odysseus0 MCP Server Shell

🚀 Shell MCP Server

A Model Context Protocol (MCP) server that provides shell command execution functionality. This server enables large language models (LLMs) to execute shell commands in a controlled manner and receive their outputs.

🚀 Quick Start

The Shell MCP Server allows LLMs to execute shell commands and obtain results. Here's a brief introduction to its main functions and usage.

✨ Features

Available Tools

• execute_command - Execute a shell command and return its output
  • Required parameters:
    • command (string): The shell command to be executed
  • Returns:
    • The command result includes:
      • command: The executed command
      • output: The combined stdout and stderr output
      • return_code: The return code of the command execution

📦 Installation

Using uv (Recommended)

When using uv, no specific installation is required. We'll 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

📚 Documentation

Configuration

Configuration for Claude.app

Add the following to your Claude settings:

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

"mcpServers": {
  "shell": {
    "command": "python",
    "args": ["-m", "mcp_server_shell"]
  }
}

Configuration for Zed

Add the following to your Zed settings.json:

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

"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

You can use the MCP monitor to debug the server. For uvx installation:

npx @modelcontextprotocol/inspector uvx mcp-server-shell

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

cd path/to/servers/src/shell
npx @modelcontextprotocol/inspector uv mcp_server_shell

Security Considerations

• Input Validation: Always validate user-provided input to avoid command injection attacks.
• Permission Management: Limit the permissions of commands executed by the server to ensure that only authorized operations are allowed.

🤝 Contribution Guidelines

To contribute to this project, please follow these steps:

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Push to your fork.
5. Submit a pull request.

If you need to report an issue or request a feature, please open an issue on GitHub.

📄 License

[Add license information here]

Thank you for using mcp-server-shell! We hope it provides powerful shell command execution capabilities for your projects.