gerard-kanters/mcp-linux-tools

📖 Description
MCP Linux Tools is an MCP (Model Context Protocol) server that exposes a secure, whitelisted set of operations on a Linux server. It allows AI assistants (such as VS Code, Claude or Cursor) to perform controlled system administration tasks like reading logs, checking service status, managing cron jobs, running WP-CLI commands, and executing sandboxed Python code—all through a uniform API with strict security constraints.
The server runs as a systemd service and communicates over HTTP. All operations are restricted by configurable whitelists (directories, services, WordPress sites). Tools return a uniform response contract {success, data, error, meta}.
✨ Features
- **🔍 Metadata & Discovery** – Server info, service whitelist, WordPress allowed sites
- **📂 File Operations** – Read files, list directories, head/tail logs (whitelisted paths only)
- **⚙️ System Services** – Check status, reload or restart whitelisted services
- **🐍 Python Sandbox** – Execute Python code (no network, 8s timeout)
- **⏰ Cron Management** – List, add, remove, enable/disable cron jobs
- **🌐 WordPress** – WP-CLI runner, cache flush, plugin/user listing, log tailing
- **🗄️ Database** – Read-only MySQL queries (dangerous queries blocked)
- **📡 Network** – Ping for connectivity testing
- **📌 Git** – Safe Git commands (no push/force)
📦 Installation
Requirements
- Python 3.13 or higher
- Root access (for systemctl and crontab)
- Linux system with systemd
Step 1: Clone Repository
Step 2: Create Python Virtual Environment
Step 3: Configure
Edit config.json and adjust the settings for your server:
- Set server_type (development or production)
- Set server_ip to your server's IP address
- Set server_name to identify this server
- Configure directory whitelists, service whitelist, and other settings as needed
See the Configuration section below for detailed information about all configuration options.
Step 4: Create Sandbox Directory
Step 5: Install Systemd Service
Create a service file: /etc/systemd/system/mcp-linux-tools.service
Enable and start the service:
Step 6: Cursor MCP Configuration
Add to your Cursor MCP configuration (usually ~/.cursor/mcp.json or in Cursor settings):
Or use direct HTTP transport in Cursor MCP settings with:
- URL: http://192.168.1.22:8765/mcp
- Transport: HTTP
Verification
Check if the server is running:
Installing Updates
To update the MCP server:
**Important**: After an update, check if config.json is still correct. New configuration options may have been added.
---
🏗️ Architecture
The server follows a modular MCP architecture:
- server.py – Entrypoint: config loading, MCP setup, tool registration, run/retry/signal handling
- config.py – Config loading and validation (fail-fast on missing fields)
- register_tools.py – Central tool registration
- core/ – Core modules:
- errors.py – Error codes (DENIED_PATH, INVALID_INPUT, COMMAND_BLOCKED, etc.)
- models.py – Pydantic models for uniform response contract
- response.py – ok(), err(), err_denied_* helpers
- security.py – Allowlist and path validation
- process.py – Subprocess runner
- tools/ – Tool modules per domain:
- discovery.py, filesystem.py, logs.py, systemd.py
- python_exec.py, wordpress.py, cron_tools.py, ops.py
All tools return a uniform response contract: {success, data, error, meta}.
---
⚙️ Configuration
All configuration is done via config.json in the root of the MCP server directory (/opt/mcp/config.json).
Configuration Sections
Server Identification
- server_type: "development" or "production"
- server_ip: IP address of the server
- server_name: Name for the MCP server
Server Listen (optional)
- server.host: Bind address (default: "0.0.0.0")
- server.port: HTTP port (default: 8765)
Logging
- logging.log_file: Path to log file
Limits
- limits.max_bytes: Maximum file size for reading (default: 524288 = 512KB)