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 uv
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" }
        }
      }
    }
  }
}

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-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.

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

run_command

A secure terminal execution server that enables controlled command execution with security features and resource limits via the Model Context Protocol (MCP).

Related Resources

Reddit Discussion about this server

Related MCP Servers

mcp-shell-server
tumf
A
security
A
license
A
quality
A 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
130
MIT License
Terminal Controller for MCP
GongRzhe
A
security
A
license
A
quality
An MCP server that enables secure terminal command execution, directory navigation, and file system operations through a standardized interface for LLMs.
Last updated -
10
81
MIT License
Super Shell MCP Server
cfdude
A
security
A
license
A
quality
An 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 -
9
75
6
MIT License
MCP Shell Server
diegofornalha
A
security
F
license
A
quality
A secure server that implements the Model Context Protocol (MCP) to enable controlled execution of authorized shell commands with stdin support.
Last updated -
1

View all related MCP servers

MCP Terminal Server