Overview

The MCP Terminal Server enables AI models to interact directly with command-line interfaces and shells through the Model Context Protocol. It provides a secure, standardized interface for executing commands, managing processes, and performing file operations while maintaining safety through command filtering and timeouts.

Created by:

Developed by GongRzhe

Key Features

⚡

Command Execution

Execute shell commands with timeout controls and security filtering

📁

File Operations

Read, write, insert, delete, and update file content with line-level precision

🔒

Security Controls

Built-in command blacklist and timeout protection for safe execution

📜

Command History

Track and review recent command executions and results

Available Tools

Quick Reference

Tool	Purpose	Category
`execute_command`	Run shell commands	Command
`get_command_history`	View command history	Command
`get_current_directory`	Get working directory	Directory
`change_directory`	Change working directory	Directory
`list_directory`	List directory contents	Directory
`read_file`	Read file content	File
`write_file`	Write to file	File
`insert_file_content`	Insert at specific lines	File
`delete_file_content`	Delete specific lines	File
`update_file_content`	Update specific lines	File

Detailed Usage

execute_command▶

Execute a shell command with optional timeout control.

// Execute a simple command
use_mcp_tool({
  server_name: "terminal",
  tool_name: "execute_command",
  arguments: {
    command: "ls -la"
  }
});

// Execute with custom timeout (60 seconds)
use_mcp_tool({
  server_name: "terminal",
  tool_name: "execute_command",
  arguments: {
    command: "npm install",
    timeout: 60
  }
});

Returns command output and exit code. Default timeout: 30 seconds.

get_command_history▶

Retrieve recent command execution history.

// Get last 10 commands (default)
use_mcp_tool({
  server_name: "terminal",
  tool_name: "get_command_history",
  arguments: {}
});

// Get last 20 commands
use_mcp_tool({
  server_name: "terminal",
  tool_name: "get_command_history",
  arguments: {
    count: 20
  }
});

Returns formatted history with timestamps and exit codes.

read_file▶

Read file content with optional line range selection.

// Read entire file
use_mcp_tool({
  server_name: "terminal",
  tool_name: "read_file",
  arguments: {
    path: "/path/to/config.json"
  }
});

// Read specific line range (lines 10-20)
use_mcp_tool({
  server_name: "terminal",
  tool_name: "read_file",
  arguments: {
    path: "/path/to/log.txt",
    start_row: 10,
    end_row: 20
  }
});

Row indexing is 0-based. End row is inclusive.

write_file▶

Write content to a file with overwrite or append mode.

// Overwrite file (default)
use_mcp_tool({
  server_name: "terminal",
  tool_name: "write_file",
  arguments: {
    path: "/path/to/output.txt",
    content: "New content here",
    mode: "overwrite"
  }
});

// Append to file
use_mcp_tool({
  server_name: "terminal",
  tool_name: "write_file",
  arguments: {
    path: "/path/to/log.txt",
    content: "Additional log entry\n",
    mode: "append"
  }
});

Returns verification of successful write operation.

list_directory▶

List files and subdirectories in a specified path.

// List current directory
use_mcp_tool({
  server_name: "terminal",
  tool_name: "list_directory",
  arguments: {}
});

// List specific directory
use_mcp_tool({
  server_name: "terminal",
  tool_name: "list_directory",
  arguments: {
    path: "/path/to/directory"
  }
});

Returns formatted list with icons for directories and files.

change_directory▶

Change the current working directory.

use_mcp_tool({
  server_name: "terminal",
  tool_name: "change_directory",
  arguments: {
    path: "/home/user/projects"
  }
});

Returns operation result confirming directory change.

insert_file_content▶

Insert content at specific line(s) in a file.

// Insert at single row
use_mcp_tool({
  server_name: "terminal",
  tool_name: "insert_file_content",
  arguments: {
    path: "/path/to/file.txt",
    content: "New line content",
    row: 5
  }
});

// Insert at multiple rows
use_mcp_tool({
  server_name: "terminal",
  tool_name: "insert_file_content",
  arguments: {
    path: "/path/to/file.txt",
    content: "Comment line",
    rows: [10, 20, 30]
  }
});

Row indexing is 0-based. Content is inserted before the specified row.

delete_file_content▶

Delete specific line(s) from a file.

// Delete single row
use_mcp_tool({
  server_name: "terminal",
  tool_name: "delete_file_content",
  arguments: {
    path: "/path/to/file.txt",
    row: 3
  }
});

// Delete multiple rows
use_mcp_tool({
  server_name: "terminal",
  tool_name: "delete_file_content",
  arguments: {
    path: "/path/to/file.txt",
    rows: [5, 10, 15]
  }
});

Row indexing is 0-based.

update_file_content▶

Update content at specific line(s) in a file.

// Update single row
use_mcp_tool({
  server_name: "terminal",
  tool_name: "update_file_content",
  arguments: {
    path: "/path/to/config.txt",
    content: "updated_value=true",
    row: 12
  }
});

// Update multiple rows with same content
use_mcp_tool({
  server_name: "terminal",
  tool_name: "update_file_content",
  arguments: {
    path: "/path/to/file.txt",
    content: "# TODO: Review this",
    rows: [25, 50, 75]
  }
});

Row indexing is 0-based. Replaces the entire line.

get_current_directory▶

Get the current working directory path.

use_mcp_tool({
  server_name: "terminal",
  tool_name: "get_current_directory",
  arguments: {}
});

Returns the absolute path of the current directory.

Installation

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal_controller"]
    }
  }
}

UV Package Manager:

uvx is the recommended method for running Python-based MCP servers. Install UV from astral.sh/uv

Security

The Terminal Controller implements robust security measures to ensure safe command execution:

Security Features

Command Timeouts: Prevent long-running or frozen processes (default: 30s)
Blacklist Filtering: Blocks dangerous commands (e.g., rm -rf /, format, mkfs)
Isolated Execution: Commands run in controlled environment with error handling
Restricted Access: Only explicitly permitted commands and directories allowed

Common Use Cases

1. Build and Deployment Automation

Execute build commands and deployment scripts:

// Run build process
use_mcp_tool({
  server_name: "terminal",
  tool_name: "execute_command",
  arguments: {
    command: "npm run build",
    timeout: 120  // 2 minutes for build
  }
});

// Deploy to production
use_mcp_tool({
  server_name: "terminal",
  tool_name: "execute_command",
  arguments: {
    command: "npm run deploy",
    timeout: 180  // 3 minutes for deployment
  }
});

2. Log Analysis

Read and analyze log files:

// Read last 50 lines of log file
use_mcp_tool({
  server_name: "terminal",
  tool_name: "execute_command",
  arguments: {
    command: "tail -n 50 /var/log/app.log"
  }
});

// Read specific error lines
use_mcp_tool({
  server_name: "terminal",
  tool_name: "read_file",
  arguments: {
    path: "/var/log/error.log",
    start_row: 100,
    end_row: 150
  }
});

3. Configuration Management

Update configuration files programmatically:

// Read current config
use_mcp_tool({
  server_name: "terminal",
  tool_name: "read_file",
  arguments: {
    path: "/etc/app/config.json"
  }
});

// Update specific configuration line
use_mcp_tool({
  server_name: "terminal",
  tool_name: "update_file_content",
  arguments: {
    path: "/etc/app/config.json",
    content: '  "debug": true,',
    row: 5
  }
});

4. Development Workflow

Manage development tasks and environment:

// Check git status
use_mcp_tool({
  server_name: "terminal",
  tool_name: "execute_command",
  arguments: {
    command: "git status"
  }
});

// Run tests
use_mcp_tool({
  server_name: "terminal",
  tool_name: "execute_command",
  arguments: {
    command: "pytest tests/",
    timeout: 60
  }
});

// Get command history
use_mcp_tool({
  server_name: "terminal",
  tool_name: "get_command_history",
  arguments: {
    count: 20
  }
});

5. File Management and Editing

Perform precise file operations:

// Insert header comment in source file
use_mcp_tool({
  server_name: "terminal",
  tool_name: "insert_file_content",
  arguments: {
    path: "/src/main.py",
    content: "# Copyright 2024 - All Rights Reserved",
    row: 0
  }
});

// Delete debug print statements
use_mcp_tool({
  server_name: "terminal",
  tool_name: "delete_file_content",
  arguments: {
    path: "/src/debug.py",
    rows: [15, 23, 47]  // Lines with debug prints
  }
});

// Update version number
use_mcp_tool({
  server_name: "terminal",
  tool_name: "update_file_content",
  arguments: {
    path: "/package.json",
    content: '  "version": "2.0.0",',
    row: 3
  }
});

Best Practices

Use Timeouts: Always set appropriate timeouts for long-running commands
Check History: Review command history to debug issues and track operations
Line-Level Edits: Use insert_file_content, update_file_content, and delete_file_content for surgical file modifications instead of overwriting entire files
Path Validation: Verify paths exist before operations with list_directory or get_current_directory
Read Before Write: Read file content before making modifications to understand structure
Security First: Never execute untrusted commands or bypass security filters

Limitations

Blacklisted Commands: Dangerous system commands are blocked for safety
Timeout Limits: Long-running processes may be terminated (default: 30 seconds)
File Access: Limited to directories accessible by the MCP server process
Platform Specific: Some commands may behave differently across operating systems

Sources

Perplexity AI MCP Server: Real-time Search & Reasoning for AI

Explore Perplexity AI MCP Server for real-time web search, advanced reasoning, and comprehensive research. Empower your AI with up-to-date information and detailed answers.

Thirdweb MCP Server

Thirdweb MCP servers enable AI agents to interact with EVM blockchains via thirdweb services, supporting multi-chain data querying, wallet and contract operations, autonomous execution, and both hosted and self-hosted deployment options.

Knowledge Graph Memory MCP: AI Persistent Memory & Entity Mgmt

Knowledge Graph Memory MCP servers empower AI with persistent memory, entity management, and relation tracking through local knowledge graph interaction.

Terminal MCP Server