# Command Executor MCP Server

A Model Context Protocol (MCP) server that executes shell commands and handles large outputs with pagination.

## Features

- **execute_command**: Executes shell commands and captures output
  - Returns full output directly if under 10,000 estimated tokens
  - For larger outputs, stores them and returns an ID for pagination
  - Supports custom working directory and timeout

- **get_output_page**: Retrieves paginated output for large command results
  - Pages contain approximately 3,000 lines each
  - Provides navigation info (current page, total pages, has next/previous)

## Installation

```bash
pip install -r requirements.txt
```

## Configuration

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "command-executor": {
      "command": "python",
      "args": ["/path/to/command_executor_mcp.py"]
    }
  }
}
```

## Usage Examples

### Execute a simple command:
```
execute_command({"command": "ls -la"})
```

### Execute with custom directory and timeout:
```
execute_command({
  "command": "find . -name '*.py'",
  "working_directory": "/Users/username/projects",
  "timeout": 60
})
```

### Retrieve paginated output:
```
get_output_page({
  "output_id": "uuid-returned-from-execute",
  "page": 1
})
```

## Token Estimation

The server estimates tokens at approximately 0.25 tokens per character. Outputs exceeding 10,000 estimated tokens are automatically paginated.