mcp-terminal

# MCP Terminal Server A secure terminal execution server implementing the Model Context Protocol (MCP). This server provides controlled command execution capabilities with security features and resource limits. ## Features - **Command Execution**: Execute shell commands with output capture and error handling - **Security Controls**: Restrict allowed commands and prevent command injection - **Resource Controls**: - Command timeouts - Maximum output size limits - **MCP Protocol Support**: - Standard MCP message format - Capability advertisement - Streaming output support ## Development ### Local Setup ```bash # Clone the repository git clone https://github.com/RinardNick/mcp-terminal.git cd mcp-terminal # Create and activate virtual environment using uv uv venv source .venv/bin/activate # or .venv\Scripts\activate on Windows # Install development dependencies uv pip install -e ".[dev]" ``` ### Publishing to PyPI ```bash # Build the package uv pip install build python -m build # Upload to PyPI uv pip install twine python -m twine upload dist/* ``` ### Testing with MCP Inspector The MCP Inspector tool can be used to test the server implementation: ```bash # Install inspector npm install -g @modelcontextprotocol/inspector # Test server npx @modelcontextprotocol/inspector python3 src/mcp_terminal/server.py --allowed-commands "python,pip,git,ls,cd" ``` ### Running Tests ```bash # Run all tests pytest tests/ # Run specific test file pytest tests/test_terminal.py # Run with coverage pytest --cov=mcp_terminal tests/ ``` ## Using with Claude Desktop Once the package is published to PyPI: 1. **Install UV** (if not already installed): ```bash pip install uv ``` 2. **Install the Package using UV**: ```bash uv pip install mcp-terminal ``` 3. **Configure Claude Desktop**: Edit your Claude Desktop config file (typically at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "mcpServers": { "terminal": { "command": "uv", "args": [ "pip", "run", "mcp-terminal", "--allowed-commands", "python,pip,git,ls,cd", "--timeout-ms", "30000", "--max-output-size", "1048576" ] } } } ``` ## Protocol Implementation The server implements the Model Context Protocol (MCP) with the following capabilities: ### Capabilities Advertisement ```json { "protocol": "1.0.0", "name": "terminal", "version": "1.1.0", "capabilities": { "execute": { "description": "Execute a terminal command", "parameters": { "command": { "type": "string", "description": "The command to execute" } }, "returns": { "type": "object", "properties": { "exitCode": { "type": "number" }, "stdout": { "type": "string" }, "stderr": { "type": "string" }, "startTime": { "type": "string" }, "endTime": { "type": "string" } } } } } } ``` ### Message Format **Request**: ```json { "type": "execute", "data": { "command": "echo 'hello world'" } } ``` **Response**: ```json { "type": "result", "data": { "command": "echo 'hello world'", "exitCode": 0, "stdout": "hello world\n", "stderr": "", "startTime": "2024-01-20T12:34:56.789Z", "endTime": "2024-01-20T12:34:56.790Z" } } ``` **Error**: ```json { "type": "error", "data": { "message": "command not allowed" } } ``` ## Security Considerations 1. **Command Validation**: - Only allowed commands can be executed - Shell operators are blocked - Command injection attempts are prevented 2. **Resource Protection**: - Command timeouts prevent hanging - Output size limits prevent memory exhaustion - Error handling for all failure cases 3. **Best Practices**: - Always set `allowed-commands` in production - Use conservative timeout and size limits - Monitor command execution logs ## Contributing 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.