princerathi1989/mcp-terminal-server

MCP Terminal Server

A simple Model Context Protocol (MCP) server that exposes a terminal tool for executing shell commands.

Features

• Terminal Tool: Execute shell commands and get their output
• Working Directory Support: Run commands in specific directories
• Error Handling: Captures both stdout and stderr
• Timeout Protection: Commands timeout after 30 seconds
• Exit Code Reporting: Shows the exit code of executed commands

Installation

The project uses uv for dependency management. Install dependencies with:

uv sync

Usage

Running the Server Locally

Start the MCP server:

uv run server.py

The server will run and wait for MCP client connections via stdio.

Running with Docker

Option 1: Using Docker Compose (Recommended)

# Build and run
docker-compose up

# Run in background
docker-compose up -d

# Stop
docker-compose down

Option 2: Using Docker directly

# Build the image
docker build -t mcp-terminal-server .

# Run the container
docker run --rm -it mcp-terminal-server

# Or use the build script
./build.sh

Option 3: Quick test

# Test the server in a container
docker run --rm -it mcp-terminal-server uv run server.py

Tool: terminal

Execute terminal commands with the following parameters:

• command (required): The shell command to execute
• working_directory (optional): Directory to run the command in (defaults to current directory)

Example Usage

{
  "name": "terminal",
  "arguments": {
    "command": "ls -la",
    "working_directory": "/home/user"
  }
}

Example Response

{
  "content": [
    {
      "type": "text",
      "text": "STDOUT:\ntotal 8\ndrwxr-xr-x 2 user user 4096 Jan 1 12:00 .\ndrwxr-xr-x 3 user user 4096 Jan 1 12:00 ..\n-rw-r--r-- 1 user user    0 Jan 1 12:00 file.txt\n\nExit code: 0"
    }
  ]
}

Security Note

⚠️ Warning: This server allows execution of arbitrary shell commands. Only use it in trusted environments and with trusted MCP clients.

Dependencies

• mcp[cli]>=1.14.1: Model Context Protocol Python SDK