Shell Server
# 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`:
```bash
# Using uv
uv sync
# Or using pip
pip install -e .
```
## Usage
### Running the Server
Run the server directly:
```bash
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):
```json
{
"mcpServers": {
"shellserver": {
"command": "python",
"args": ["/path/to/shellserver/server.py"]
}
}
}
```
**Cursor** (similar configuration):
```json
{
"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
```json
{
"name": "terminal",
"arguments": {
"command": "ls -la"
}
}
```
```json
{
"name": "terminal",
"arguments": {
"command": "pwd",
"working_directory": "/tmp"
}
}
```
```json
{
"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](https://github.com/modelcontextprotocol/python-sdk)
- FastMCP for simplified server creation
## License
MIT
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusing it with another. Its purpose—execute a shell command—is explicit and unambiguous.
A single tool cannot exhibit inconsistency, and 'terminal' is clear and readable. It is a noun rather than a verb_noun action name, so it does not fully follow the ideal convention.
A shell server naturally needs only one general-purpose execution tool, so the count is well-scoped rather than bloated. It is on the thin side, but additional tools would likely be redundant wrappers.
Because arbitrary shell commands can cover file operations, process control, and environment inspection, the surface is functionally broad. Minor gaps exist around streaming output, session persistence, and structured error handling, but these are workable via shell.