serverdaun/shell-mcp-server

MCP Shell Server

A secure Model Context Protocol (MCP) server that provides terminal command execution and file reading capabilities with built-in safety mechanisms.

Features

• Secure Command Execution: Run terminal commands with comprehensive security restrictions
• File Resource Access: Read specific files through MCP resource endpoints
• Safety First: Built-in protection against dangerous commands and operations
• Async/Await Support: Fully asynchronous implementation for optimal performance
• Docker Support: Containerized deployment with multi-stage builds
• Cross-Platform: Works on macOS, Linux, and Windows

Security Features

The server implements multiple layers of security to prevent dangerous operations:

• Command Blacklist: Blocks dangerous commands like rm, dd, format, fdisk
• Pattern Detection: Prevents risky patterns like file redirections and system modifications
• Execution Timeout: Commands are limited to prevent hanging processes
• Error Handling: Comprehensive error handling and logging

Blocked Commands

• File deletion: rm, rmdir, del, unlink, shred
• Disk operations: dd, format, fdisk, mkfs, wipefs
• Dangerous patterns: >, >>, /dev/null, sudo rm

Installation

Prerequisites

• Python 3.12 or higher
• uv package manager (recommended)

Local Development

1. Clone the repository:

   git clone <repository-url>
   cd shellserver
   

2. Install dependencies with uv:

   uv sync
   

3. Or install with pip:

   pip install -r requirements.txt
   

Docker Installation

1. Build the Docker image:

   docker build -t mcp-shell-server .
   

2. Run the container:

   docker run -it mcp-shell-server
   

Usage

Running the Server

With uv:

uv run server.py

With Python:

python server.py

With Docker:

docker run -it mcp-shell-server

Available Tools

run_command

Execute terminal commands securely.

Parameters:

• command (string): The shell command to execute

Returns:

• stdout (string): Command output
• stderr (string): Error output
• returncode (int): Exit code

Example:

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

Available Resources

file://mcpreadme

Read the contents of a specific markdown file located at ~/Desktop/ML/mcpreadme.md.

Example:

{
  "uri": "file://mcpreadme"
}

Configuration

The server runs on standard I/O (stdio) transport by default. You can modify the transport method in the server.py file:

if __name__ == "__main__":
    mcp.run("stdio")  # or "sse" for Server-Sent Events

Development

Project Structure

shellserver/
├── server.py          # Main MCP server implementation
├── pyproject.toml     # Project configuration
├── requirements.txt   # Python dependencies
├── Dockerfile         # Container configuration
├── uv.lock           # Dependency lock file
└── README.md         # This file

Adding New Tools

To add new tools, use the @mcp.tool() decorator:

@mcp.tool()
async def your_new_tool(param: str) -> dict:
    """Your tool description"""
    # Tool implementation
    return {"result": "success"}

Adding New Resources

To add new resources, use the @mcp.resource() decorator:

@mcp.resource("file://your-resource")
async def your_resource() -> str:
    """Resource description"""
    # Resource implementation
    return "resource content"

Error Handling

The server implements comprehensive error handling:

• Security Violations: Commands that match dangerous patterns return security errors
• Execution Errors: Failed commands return error details in stderr
• File Access Errors: Resource access failures return descriptive error messages
• Timeout Handling: Long-running commands are terminated after 30 seconds

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License.

You are free to use, modify, and distribute this software in accordance with the terms of the MIT License.

See the LICENSE file in the repository for full license text.

Support

For issues and questions:

• Create an issue in the repository
• Check the MCP documentation

Dependencies

• mcp[cli]: Model Context Protocol implementation
• Python 3.12+: Required Python version
• FastMCP: MCP server framework
• asyncio: Asynchronous programming support