# 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
