Terminal Command Runner MCP Server: Lightning Execution & Automation

What is Terminal Command Runner MCP Server: Lightning Execution & Automation?

Terminal Command Runner MCP Server is a high-performance middleware solution designed to empower AI assistants with seamless terminal command execution and file system management capabilities. Built on the Model Control Protocol (MCP), it exposes a RESTful API interface enabling secure and efficient interaction with system processes, files, and utilities. This server acts as a bridge between AI agents and underlying system operations, abstracting complex low-level tasks into manageable API calls.

How to use Terminal Command Runner MCP Server: Lightning Execution & Automation?

Deployment follows a straightforward workflow:

• Install dependencies using Python 3.13+ and the uv package manager
• Configure environment variables and MCP settings through ~/.cursor/mcp.json
• Launch the server to expose API endpoints for command execution and file operations
• Integrate with AI systems via REST API calls to trigger processes, monitor outputs, and manage files programmatically

Key Features of Terminal Command Runner MCP Server: Lightning Execution & Automation?

• Adaptive Process Control - Execute commands with configurable timeouts, manage background processes, and retrieve real-time outputs
• Granular File Management - Full CRUD capabilities for files/directories, including pattern-based searches and metadata interrogation
• Security Framework - Command blacklisting, file size restrictions, and mathematical expression safeguards to prevent misuse
• Advanced Utilities - Text editing with diff-style syntax, system resource monitoring, and expression evaluation
• Scalable Architecture - Built for high-throughput environments with background process isolation and session management

Use cases of Terminal Command Runner MCP Server: Lightning Execution & Automation?

• Automating CI/CD pipelines with background process monitoring
• Powering conversational AI agents to execute system commands securely
• Building cross-platform file management solutions with pattern-based search
• Implementing server health dashboards via system information APIs
• Creating secure development sandboxes with restricted command execution

FAQ from Terminal Command Runner MCP Server: Lightning Execution & Automation?

• How does security work? - Mandatory command whitelisting, input sanitization, and rate limiting protect against unauthorized operations
• What OS platforms are supported? - Fully functional on Linux, macOS, and Windows environments
• Can I customize timeouts? - Timeout values are configurable per API request header parameters
• How are long-running processes handled? - Background process isolation with dedicated session tracking ensures stability
• What authentication methods are available? - Supports token-based authentication through environment variables

Terminal Command Runner MCP Server

A powerful Model Control Protocol (MCP) server that provides terminal command execution and file system management capabilities for AI assistants through a RESTful API interface.

🌟 Features

Terminal Management

• Execute commands with configurable timeouts
• Manage long-running processes in the background
• Fetch output from active command sessions
• List all active sessions and system processes
• Terminate or kill processes
• Command blacklisting for security

File System Operations

• Read and write files
• Create directories
• List directory contents
• Move/rename files
• Search for files using glob patterns
• Get detailed file information

Advanced Features

• Precise text editing with search and replace
• System information retrieval
• Mathematical expression evaluation

🚀 Quick Start

Prerequisites

• Python 3.13+
• uv package manager (recommended)

Installation

1. Clone the repository:

git clone https://github.com/neoforge-dev/neoforge-mcp-server.git
cd python-server-mcp

2. Create a virtual environment and install dependencies:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

3. Start the MCP server:

python server.py

The server will start on http://0.0.0.0:8000.

🧪 Testing

The project includes a comprehensive test suite to verify functionality:

# Install test dependencies
uv pip install -r requirements.txt

# Run all tests
./run_tests.py

# Run tests with coverage report
./run_tests.py --coverage

# Run tests with verbose output
./run_tests.py --verbose

# Run specific test file
./run_tests.py --test tests/test_command_execution.py

The test suite covers:

• Command execution and process management
• File system operations
• System utilities
• Security features

🔧 Configuration

Configure Cursor to use this MCP service by adding it to your ~/.cursor/mcp.json file:

{
  "mcpServers": {
    "NeoMCP": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/path/to/python-server-mcp/server.py"
      ]
    }
  }
}

📖 API Reference

Terminal Tools

• execute_command: Run commands with configurable timeouts
• read_output: Get output from running processes
• force_terminate: Stop a running command
• list_sessions: Show all active command sessions
• list_processes: View all system processes
• kill_process: Kill processes by PID
• block_command: Add commands to the blacklist
• unblock_command: Remove commands from the blacklist

File System Tools

• read_file: Read file contents
• write_file: Write data to a file
• create_directory: Create new directories
• list_directory: List contents of a directory
• move_file: Move or rename files and directories
• search_files: Find files matching patterns
• get_file_info: Get detailed file information

Edit Tools

• edit_block: Apply precise text replacements using diff-like syntax

System Tools

• system_info (resource): Get detailed system information
• calculate: Evaluate mathematical expressions

🔒 Security Considerations

• The server implements command blacklisting to prevent dangerous commands
• File size limits for read operations
• Expression evaluation safeguards
• Default command safety checks

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.