Command Executor

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

pip install -r requirements.txt

Configuration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.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.