MCP Shell Server

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

Features

• Terminal Tool: Execute shell commands and get results

• Safety Features: 30-second timeout and error handling

• Flexible: Optional working directory parameter

• Claude Integration: Tool named run_command for easy Claude integration

Related MCP server: Terminal Controller for MCP

Installation

The project uses uv for dependency management. Dependencies are already configured in pyproject.toml.

Usage

Running the Server

# Using uv
uv run python server.py

# Or directly with Python
python server.py

The server will start and wait for MCP client connections via stdin/stdout.

Tool Description

The server exposes a run_command tool with the following parameters:

• command (required): The shell command to execute

• working_directory (optional): Directory to run the command in

Example Usage

The terminal tool can be used to run commands like:

• ls -la - List files in current directory

• pwd - Get current working directory

• echo "Hello World" - Print text

• python --version - Check Python version

Response Format

The tool returns a dictionary with:

• stdout: Standard output from the command

• stderr: Standard error from the command

• return_code: Exit code of the command

• success: Boolean indicating if command succeeded (return code 0)

MCP Integration

This server follows the Model Context Protocol specification and can be integrated with MCP clients like Claude Desktop. The tool is named run_command for easy identification and use.

Security Note

This server allows execution of arbitrary shell commands. Use with caution and ensure proper access controls are in place in production environments.

Development

This is a simple implementation using the MCP Python SDK with FastMCP. The server can be extended with additional tools as needed.