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.