A
securityA
licenseA
qualityA secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.
Last updated -
1
154
MIT License
This server allows you to securely execute terminal commands with controlled access and resource management:
Command Execution: Run shell commands and capture their output (stdout, stderr) along with exit codes
Security Controls: Restrict commands to a predefined list to prevent unauthorized actions and command injection
Resource Management: Set limits on execution time (timeout) and maximum output size to prevent resource exhaustion
Customizable Settings: Configure allowed commands and resource limits on a per-request basis
Communication: Uses the Model Context Protocol (MCP) for interaction
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
# 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
# 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:
# 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
# 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:
Install UV (if not already installed):
pip install uvInstall the Package using UV:
uv pip install mcp-terminalConfigure Claude Desktop: Edit your Claude Desktop config file (typically at
~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS):{ "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
{
"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:
{
"type": "execute",
"data": {
"command": "echo 'hello world'"
}
}
Response:
{
"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:
{
"type": "error",
"data": {
"message": "command not allowed"
}
}
Security Considerations
Command Validation:
Only allowed commands can be executed
Shell operators are blocked
Command injection attempts are prevented
Resource Protection:
Command timeouts prevent hanging
Output size limits prevent memory exhaustion
Error handling for all failure cases
Best Practices:
Always set
allowed-commandsin productionUse conservative timeout and size limits
Monitor command execution logs
Contributing
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add some amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Related MCP Servers
- AsecurityAlicenseAqualityAn MCP server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface for LLMs.Last updated -1091MIT License
- AsecurityAlicenseAqualityAn MCP server that enables secure execution of shell commands across Windows, macOS, and Linux with built-in whitelisting and approval mechanisms for enhanced security.Last updated -94210MIT License
- AsecurityFlicenseAqualityA secure server that implements the Model Context Protocol (MCP) to enable controlled execution of authorized shell commands with stdin support.Last updated -1