Neoforge MCP Server

🚀 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 RESTful API interfaces.

✨ Features

Terminal Management

• Execute commands with configurable timeouts.
• Manage long-running background processes.
• Get output from active command sessions.
• List all active sessions and system processes.
• Terminate or kill processes.
• Command blacklist function (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 (including search and replace).
• System information retrieval.
• Mathematical expression calculation.

🚀 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 run at http://0.0.0.0:8000.

🧪 Testing

This 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 files
./run_tests.py --test tests/test_command_execution.py

The test suite covers the following:

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

🔧 Configuration

Configure Cursor by adding the MCP service to the ~/.cursor/mcp.json file:

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

📚 Documentation

Terminal Tools

• execute_command: Command execution with timeout configuration.
• read_output: Get the output of a running process.
• force_terminate: Stop a running command.
• list_sessions: Display all active command sessions.
• list_processes: View all system processes.
• kill_process: Kill a process by PID.
• block_command: Add a command to the blacklist.
• unblock_command: Remove a command from the blacklist.

File System Tools

• read_file: Read file contents.
• write_file: Write data to a file.
• create_directory: Create a new directory.
• list_directory: List directory contents.
• move_file: Move or rename a file.
• Get detailed file information.

Advanced Tools

• Precise text editing (including search and replace).
• System information retrieval.
• Mathematical expression calculation.

🤝 Contribution Guidelines

Contributions are welcome! Please refer to CONTRIBUTING.md to learn how to participate.

📄 License

This project is protected by LICENSE.