How do I use Shell Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Shell Server list all files in the current directory" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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