neoforge-dev/neoforge-mcp-server
If you are the rightful owner of neoforge-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Terminal Command Runner MCP Server is 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.
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
- Clone the repository:
git clone https://github.com/neoforge-dev/neoforge-mcp-server.git
cd python-server-mcp
- Create a virtual environment and install dependencies:
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e .
- 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 timeoutsread_output: Get output from running processesforce_terminate: Stop a running commandlist_sessions: Show all active command sessionslist_processes: View all system processeskill_process: Kill processes by PIDblock_command: Add commands to the blacklistunblock_command: Remove commands from the blacklist
File System Tools
read_file: Read file contentswrite_file: Write data to a filecreate_directory: Create new directorieslist_directory: List contents of a directorymove_file: Move or rename files and directoriessearch_files: Find files matching patternsget_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 informationcalculate: 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.
