shellserver
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@shellserver list 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.
shellserver
A small Model Context Protocol (MCP) server built with the Python MCP SDK (FastMCP). It exposes one tool that runs shell commands on the machine where the server process runs.
Requirements
Python 3.14+ (see
pyproject.toml)uv for installing and running dependencies
Related MCP server: Shell MCP Server
Setup
Clone or copy this repository, then from the project root:
uv syncRunning the server
The server uses stdio transport (the default for FastMCP).
uv run python server.pyDo not pipe extra data to stdout from the server process; MCP uses stdout for JSON-RPC. Logging in server.py is directed to stderr.
Tool: terminal_tool
Parameter | Type | Required | Default | Description |
| string | yes | — | Shell command to run |
| string | no | — | Working directory for the subprocess |
| number | no |
| Seconds to wait before killing the process |
The tool returns a single text block containing exit_code, stdout, and stderr. If the command exceeds the timeout, the process is terminated and the response indicates a timeout.
Connecting a client (example of running locally)
Point your MCP host at uv with this project as the working directory. Example configuration shape:
{
"mcpServers": {
"shellserver": {
"command": "uv",
"args": ["run", "python", "server.py"],
"cwd": "/absolute/path/to/shellserver"
}
}
}Adjust the key name and cwd to match your editor or client.
Security
This server executes arbitrary shell commands on the host. Anyone who can invoke MCP tools against this server effectively has shell access to that machine. Use only on trusted hosts, with trusted clients, and with clear understanding of the risk.
Available Tools
2 toolsbenign_toolBenign ToolC
Download and return a fixed text file via curl.
Inputs: timeout_seconds. Returns: result
terminal_toolTerminal ToolB
Run a shell command on the host and return stdout, stderr, and exit code.
The command is executed with the system shell. Use only in trusted environments.
Inputs: command (required), cwd, timeout_seconds. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one downloads a fixed text file, the other executes shell commands. There is no ambiguity between them.
Both tool names follow a consistent adjective_noun pattern in snake_case (benign_tool, terminal_tool), making them predictable and clear.
With only 2 tools, the server feels thin for a shell execution server. While it covers the basic need, it is below the typical well-scoped range of 3-15 tools.
The core functionality of running shell commands is covered by terminal_tool. The presence of benign_tool as a fixed downloader is a minor addition; agents can work around the lack of other shell utilities like file listing.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
I run shell commands on your private cloud environment (bash, sh, zsh)
Related MCP Servers
- AlicenseAqualityAmaintenanceA secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.1202MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that allows LLMs to execute shell commands and receive their output in a controlled manner.7MIT
- FlicenseBqualityDmaintenanceA Model Context Protocol server that enables LLM applications to safely execute shell commands with error handling and timeout settings.1-
- AlicenseAqualityAmaintenanceA Model Context Protocol server that allows LLMs to securely execute shell commands on remote Linux and Windows systems via SSH. It supports password and key-based authentication, command timeouts, and sudo elevation for administrative tasks.1510,581 npm893MIT