Terminal Command Runner

You can run and manage this MCP Server locally to execute terminal commands, manage files, and query system information through a unified RESTful interface. It provides practical capabilities for AI assistants to interact with the host environment securely and efficiently.

How to use

Connect your MCP client to the local server and start issuing operations to run commands, manipulate files, and perform system tasks. You can launch and manage terminal sessions, fetch command output, read and write files, create directories, search for files, and perform precise text edits. Use the available tools to monitor system information and evaluate mathematical expressions. When you need to stop a running command, you can terminate it safely. A command blacklist helps prevent execution of restricted commands.

How to install

Prerequisites
- Python 3.13+
- uv package manager (recommended)

Installation
1. Clone the repository:
```bash
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.

## Additional notes

Configuration and usage details are designed to help you integrate this MCP server into your workflow. The server exposes terminal management, file system operations, edit capabilities, and system utilities through a straightforward runtime. Ensure you run the server from a trusted environment and follow security best practices, including keeping the command blacklist updated and applying appropriate access controls to the API.

## Configuration and scope

To run this MCP server locally, use the following runtime command and connect your MCP client to the local endpoint. The server listens on port 8000 by default and accepts commands over its HTTP REST interface.

## Security considerations

The server includes a command blacklist to prevent execution of dangerous commands and imposes file size limits for read operations. It also applies safeguards for expression evaluation and implements default command safety checks to minimize risk in automated environments.

## Troubleshooting

If the server fails to start, verify that Python 3.13+ is installed and that port 8000 is not in use by another process. Activate the virtual environment before running the server and ensure you are in the correct directory when invoking `python server.py`. If you encounter permission errors, run with elevated privileges or adjust file system permissions accordingly.

## Available tools

### execute\_command

Run terminal commands with configurable timeouts and capture output from the corresponding process.

### read\_output

Fetch the output from active command sessions.

### force\_terminate

Safely stop a running command session before completion.

### list\_sessions

List all active command sessions and their statuses.

### list\_processes

Display current system processes for monitoring.

### kill\_process

Terminate a process by its PID.

### block\_command

Add commands to a blacklist to restrict execution for security.

### unblock\_command

Remove commands from the blacklist to restore capability.

### read\_file

Read contents of a specified file.

### write\_file

Write data to a file, overwriting or appending as configured.

### create\_directory

Create new directories on the filesystem.

### list\_directory

List the contents of a directory.

### move\_file

Move or rename files and directories.

### search\_files

Search for files using glob patterns.

### get\_file\_info

Get detailed information about a file or directory.

### edit\_block

Apply precise text replacements using diff-like syntax.

### system\_info

Retrieve detailed system information for diagnostics.

### calculate

Evaluate mathematical expressions.