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):
- Install the Package using UV:
uv pip install mcp-terminal
- Configure Claude Desktop:
Edit your Claude Desktop config file (typically at
~/Library/Application Support/Claude/claude_desktop_config.json on 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" }
}
}
}
}
}
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-commands in production - Use 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.