A simple MCP server that exposes a terminal tool for executing shell commands.
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 intimeout(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
shlexto 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
Tools (1)
terminalExecute shell commands with optional working directory and timeout settings.Configuration
{"mcpServers": {"shellserver": {"command": "python", "args": ["/path/to/shellserver/server.py"]}}}