MCP Terminal

🚀 MCP Terminal Server

A secure terminal execution server implementing the Model Context Protocol (MCP). This server provides controlled command execution with security features and resource limitations.

🚀 Quick Start

The MCP Terminal Server is a secure solution for executing commands with MCP protocol support. It offers various features such as command execution, security control, and resource management.

✨ Features

• Command Execution: Execute shell commands and capture output with error handling.
• Security Control: Restrict allowed commands and prevent command injection.
• Resource Control:
  • Command timeout.
  • Maximum output size limitation.
• MCP Protocol Support:
  • Standard MCP message format.
  • Function advertisement.
  • Streaming output support.

📦 Installation

Local Setup

# Clone the repository
git clone https://github.com/RinardNick/mcp-terminal.git
cd mcp-terminal

# Create and activate a 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 the 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 a specific test file
pytest tests/test_terminal.py

# Run with coverage
pytest --cov=mcp_terminal tests/

💻 Usage Examples

Using with Claude Desktop

Once the package is published to PyPI:

1. Install UV (if not already installed):

   pip install uv
   

2. Install the package using UV:

   uv pip install mcp-terminal
   

3. Configure Claude Desktop: Edit your Claude Desktop configuration file (usually located 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"
         ]
       }
     }
   }
   

📚 Documentation

Protocol Implementation

The server implements the Model Context Protocol (MCP) with the following features:

Function Advertisement

{
  "protocol": "1.0.0",
  "functions": {
    "terminal": {
      "type": "terminal",
      "version": "1.0"
    }
  }
}

Message Format

All messages follow the following structure:

{
  "id": string,
  "command": string,
  "args": array,
  "result": any,
  "error": string | null
}

Security Considerations

• Always set allowed-commands in a production environment.
• Use conservative timeout and size limits.
• Monitor command execution logs.

Contributing

1. Fork the repository.
2. Create a 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 file for details.