# 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