Shell Server - MCP Terminal Tool

A simple MCP (Model Context Protocol) server that exposes a terminal tool for executing shell commands.

Features

• Execute shell commands via MCP protocol
• Support for custom working directories
• Configurable timeout for command execution
• Safe command parsing using shlex
• Proper error handling and output capture

Installation

Install dependencies using uv (recommended) or pip:

# Using uv
uv sync

# Or using pip
pip install -e .

Usage

Running the Server

Run the server directly:

python server.py

The server uses stdio transport by default, which is suitable for MCP clients like Claude Desktop or Cursor.

MCP Client Configuration

To use this server with an MCP client, add it to your client configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "shellserver": {
      "command": "python",
      "args": ["/path/to/shellserver/server.py"]
    }
  }
}

Cursor (similar configuration):

{
  "mcpServers": {
    "shellserver": {
      "command": "python",
      "args": ["/path/to/shellserver/server.py"]
    }
  }
}

Tool Usage

The server exposes a single tool called terminal with the following parameters:

• command (required): The shell command to execute (e.g., "ls -la", "pwd", "echo hello")
• working_directory (optional): The working directory to run the command in
• timeout (optional): Timeout in seconds (default: 30.0)

Example Tool Calls

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

{
  "name": "terminal",
  "arguments": {
    "command": "pwd",
    "working_directory": "/tmp"
  }
}

{
  "name": "terminal",
  "arguments": {
    "command": "echo 'Hello, World!'",
    "timeout": 10.0
  }
}

Security Considerations

⚠️ Warning: This server allows execution of arbitrary shell commands. Use with caution:

• The server executes commands in the context of the user running it
• Commands are parsed using shlex to handle quoted arguments safely
• A timeout is enforced to prevent long-running commands
• Consider running the server in a restricted environment or container for production use

Development

The server is built using:

• MCP Python SDK
• FastMCP for simplified server creation

License

MIT