MCPilot
Provides tools for interacting with Git repositories, including checking status, viewing diffs, reading commit logs, and running tests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCPilot Why is my system slow? Check CPU and memory."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCPilot
MCP-based agentic Linux diagnostic assistant — answers natural-language questions like "why is my laptop slow" by having Gemini select and call typed, sandboxed tools exposed by a custom MCP server, iterating through a LangGraph state machine until it has enough evidence for a diagnosis.
Local-only · Ubuntu · CLI · No arbitrary shell · Human-in-the-loop for mutations
Architecture
USER
│
▼
CLI Interface (rich)
│
▼
┌─────────────────┐
│ LangGraph │
│ Diagnostic Agent│◄──── Gemini (function calling)
└────────┬────────┘
│
MCP Client (stdio)
│
MCP Protocol
│
▼
┌─────────────────┐
│ MCPilot Server │ (MCPServer, subprocess-launched)
└────────┬────────┘
│
┌───────────────┼────────────────┐
│ │ │
▼ ▼ ▼
System Filesystem Git
/proc, psutil POSIX APIs, Git CLI via
systemd, path allow-list controlled
journalctl subprocessLayering rule: MCP decorators call a core Linux-abstraction layer; they never contain OS logic themselves.
server/tools/system.py → server/core/linux.py → /proc, psutil, uname
server/tools/services.py → server/core/systemd.py → systemctl, journalctl
server/tools/filesystem.py → server/core/fs.py → pathlib / POSIX APIs
server/tools/git.py → server/core/git.py → git CLI (controlled subprocess)Related MCP server: incident-tool
Tool Catalogue (18 tools)
Tool | Module | Returns | Risk |
| system |
| READ_ONLY |
| system |
| READ_ONLY |
| system |
| READ_ONLY |
| system |
| READ_ONLY |
| system |
| READ_ONLY |
| system |
| READ_ONLY |
| services |
| READ_ONLY |
| services |
| READ_ONLY |
| services |
| READ_ONLY |
| services |
| APPROVAL_REQUIRED |
| filesystem |
| READ_ONLY |
| filesystem |
| READ_ONLY |
| filesystem |
| READ_ONLY |
| filesystem |
| READ_ONLY |
| git |
| READ_ONLY |
| git |
| READ_ONLY |
| git |
| READ_ONLY |
| git |
| READ_ONLY |
There is intentionally no delete_file, sudo_command, or generic shell tool.
Security Model
MCPilot's security story is defense-in-depth across four layers:
No arbitrary shell tool — Every capability is a specific, narrowly-scoped Python function with a fixed subprocess argument list. Never
shell=True, never string-interpolated commands.Path restriction — All filesystem and Git tools validate paths against an explicit allow-list (
~/Projects,~/Documents). Symlink-resolved, checked withis_relative_to(). Seeserver/core/fs.py::validate_path.Service name injection prevention — A strict regex (
^[a-zA-Z0-9@_.\-]+$) rejects;,|,&,$, backticks, whitespace, and path separators. Seeserver/core/systemd.py::validate_service_name.Risk classification + human approval — Every tool has a risk level (
READ_ONLY,APPROVAL_REQUIRED,DENIED). Unknown tools default toDENIED(fail closed). The only mutating tool (restart_service) pauses for explicityconfirmation.Audit logging — Every tool call is logged to
logs/audit.jsonlwith timestamp, tool, arguments, risk, approval status, and outcome.Safe subprocess runner — All subprocess calls go through a single
run_safe()function: alwaysshell=False, always list args, always with timeout.
Full threat model: docs/security.md
Quick Start
# Prerequisites: Ubuntu, Python 3.12+, uv
git clone <repo-url> && cd mcpilot
# Install dependencies
uv sync
# Set Gemini API key
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
# Run tests (44 tests, all layers)
PYTHONPATH="" uv run python -m pytest tests/ -v --override-ini="asyncio_mode=auto"
# Interactive mode
uv run python -m cli.main
# One-shot mode
uv run python -m cli.main "Why is my system slow?"Example Traces
System Diagnosis
You: Why is my system slow?
[Agent] Analyzing request...
[MCP] get_cpu_usage()
[MCP] get_memory_usage()
[MCP] list_processes(limit=20)
[MCP] get_disk_usage()
[Agent] Evaluating evidence...
[Agent] Generating diagnosis...
Diagnosis: Memory pressure (92% used, 70% swap) driven by firefox.
Confidence: HIGH.Service Diagnosis
You: Why isn't PostgreSQL working?
[Agent] Analyzing request...
[MCP] get_service_status(service='postgresql')
[MCP] get_service_logs(service='postgresql')
[MCP] get_listening_ports()
[MCP] list_processes(limit=20)
[Agent] Evaluating evidence...
[Agent] Generating diagnosis...
Diagnosis: systemd shows failed; journal shows "address already in use";
port 5432 is held by PID <n> (<process>). Confidence: HIGH.Safety Demo
You: Restart PostgreSQL
[Agent] Analyzing request...
┌──────────────────────────────┐
│ MCPilot requests action │
├──────────────────────────────┤
│ Tool: restart_service │
│ Service: postgresql │
│ │
│ Reason: service action │
│ requested by diagnostic agent│
│ │
│ Approve? [y/N] │
└──────────────────────────────┘Test Suite
Layer | Tests | What it covers |
Layer 1 — Core Linux | 8 |
|
Layer 2 — MCP Protocol | 4 | 18 tools registered, schemas, descriptions |
Layer 3 — Security | 24 | Path traversal, service injection, unknown tools, output limits |
Layer 4 — Agent | 8 | Policies, iteration cap, approval rejection, state integrity |
Total | 44 |
Confidence Labels
Confidence is a discrete, explainable label — not a calibrated statistical score:
HIGH: ≥3 independent observations point to the same cause
MEDIUM: Some supporting evidence, but a confirming observation is missing
LOW: Evidence is thin, iteration cap was hit, or observations conflict
Project Structure
mcpilot/
├── server/
│ ├── main.py # MCPServer app, registers all 18 tools
│ ├── tools/ # MCP tool wrappers (thin, no OS logic)
│ │ ├── system.py # 6 system tools
│ │ ├── services.py # 4 service tools (incl. restart_service)
│ │ ├── filesystem.py # 4 filesystem tools
│ │ └── git.py # 4 git tools
│ ├── core/ # Linux abstraction layer
│ │ ├── linux.py # /proc + psutil parsing
│ │ ├── systemd.py # systemctl/journalctl wrappers
│ │ ├── fs.py # path validation + file ops
│ │ ├── git.py # git subprocess wrappers
│ │ └── command.py # shared safe-subprocess runner
│ ├── policies.py # risk classification map
│ ├── schemas.py # all Pydantic models
│ └── audit.py # JSONL audit logger
├── client/
│ └── mcp_client.py # MCP stdio client
├── agent/
│ ├── state.py # DiagnosticState TypedDict
│ ├── graph.py # LangGraph wiring
│ ├── nodes.py # 4 LangGraph nodes
│ ├── prompts.py # LLM prompt templates
│ └── tool_adapter.py # MCP → Gemini function declarations
├── cli/
│ └── main.py # CLI entrypoint, rich output, approval UI
├── tests/ # 44 tests across 4 layers
│ ├── server/ # Layer 1+2 tests
│ ├── agent/ # Layer 4 tests
│ └── security/ # Layer 3 tests (interview demo suite)
├── docs/ # Architecture, security, MCP docs
├── examples/ # Captured diagnostic transcripts
└── logs/ # audit.jsonl (gitignored)License
MIT
Available Tools
18 toolsget_cpu_usageA
Returns current CPU utilization as overall and per-core percentages, plus 1/5/15-minute load averages.
Use this when investigating high CPU usage, system slowness, or load-related issues. Does not modify system state.
Inputs: no named parameters. Returns: core_count, load_average_1m, load_average_5m, overall_percent, +2 more
get_disk_usageA
Returns disk usage for all mounted partitions: total, used, free in GB
and used percentage per mount point.
Use this when investigating low disk space, full partitions, or storage
issues. Does not modify system state.
Inputs: no named parameters. Returns: result
get_file_metadataA
Returns metadata about a file or directory: path, size, type, modification
time, and permissions. Path must be within allowed roots.
Use this when investigating file properties, checking permissions, or
assessing file sizes. Does not modify system state.
Inputs: path (required). Returns: result
get_listening_portsA
Returns all currently listening TCP and UDP ports with their associated process information (PID, process name, bind address).
Use this when investigating port conflicts, checking if a service is listening, or diagnosing network issues. Does not modify system state.
Inputs: no named parameters. Returns: result
get_memory_usageA
Returns current system memory and swap utilization as percentages and GB.
Use this when investigating high memory usage, swapping, or general system slowdown. Does not modify system state.
Inputs: no named parameters. Returns: used_gb, total_gb, available_gb, swap_used_gb, +3 more
get_process_infoA
Returns detailed information about a specific process: PID, parent PID,
name, status, user, CPU%, memory%, command line, and working directory.
Use this when investigating a specific process identified by list_processes
or other tools. Does not modify system state.
Inputs: pid (required). Returns: result
get_service_logsA
Returns the most recent journal log lines for a systemd service.
Use this when investigating why a service failed, crashed, or is misbehaving. Does not modify system state.
Inputs: service (required), lines. Returns: result
get_service_statusA
Returns the systemd status of a service: active state, sub-state,
whether enabled, and activation timestamp.
Use this when investigating whether a specific service is running,
failed, or misconfigured. Does not modify system state.
Inputs: service (required). Returns: result
get_system_infoA
Returns basic system information: hostname, OS, kernel version,
architecture, uptime, and CPU count.
Use this when investigating general system identity, checking OS version,
or assessing basic system health. Does not modify system state.
Inputs: no named parameters. Returns: os_name, hostname, cpu_count, os_version, +3 more
git_diffA
Returns the Git diff for a repository, showing changed files and diff text. Output is capped to prevent context flooding, with a truncated flag if the cap was hit. The repo path must be within allowed roots.
Use this when investigating what code changes were made, comparing working tree to index, or reviewing staged changes. Does not modify system state.
Inputs: repo (required), cached. Returns: result
git_logA
Returns the most recent Git log entries: commit hash, author, date, and
message. Limited to max_entries (max 100). The repo path must be within
allowed roots.
Use this when investigating recent commits, looking for when a change was
made, or identifying who made modifications. Does not modify system state.
Inputs: repo (required), max_entries. Returns: result
git_statusA
Returns the Git status of a repository: current branch, ahead/behind
counts, modified files, untracked files, and deleted files.
The repo path must be within allowed roots (~/Projects, ~/Documents).
Use this when investigating uncommitted changes, branch status, or
repository state. Does not modify system state.
Inputs: repo (required). Returns: result
list_directoryA
Lists the contents of a directory: file/directory names, types, and sizes.
Path must be within allowed roots (~/Projects, ~/Documents).
Use this when investigating directory contents, checking project structure,
or looking for specific files. Does not modify system state.
Inputs: path (required). Returns: result
list_processesA
Returns a list of running processes sorted by CPU usage, showing PID,
name, CPU%, memory%, and status. Limited to `limit` entries (max 200).
Use this when investigating which processes are consuming the most
resources. Does not modify system state.
Inputs: limit. Returns: result
read_fileA
Reads the text contents of a file (capped at 100KB). Path must be within
allowed roots (~/Projects, ~/Documents).
Use this when investigating file contents, checking configuration files,
or reading source code. Does not modify system state.
Inputs: path (required). Returns: result
restart_serviceA
Restarts a systemd service. This is a STATE-CHANGING operation that REQUIRES human approval before execution.
Use this only when a service needs to be restarted as a remediation step and the user has been informed. This is the only mutating tool in MCPilot.
Inputs: service (required). Returns: result
run_testsA
Runs pytest in a repository using a fixed, MCPilot-chosen command (never an LLM-supplied command). Returns pass/fail status, summary, and list of failing tests. The repo path must be within allowed roots.
Use this when investigating test failures or verifying that changes haven't broken tests. Does not modify system state (runs read-only tests).
Inputs: repo (required). Returns: result
search_filesA
Searches for files matching a glob pattern within a directory tree. Results are capped at 100 entries. Path must be within allowed roots.
Use this when looking for specific files by name or extension within a project. Does not modify system state.
Inputs: path (required), pattern (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool targets a specific resource and action: system metrics (cpu, memory, disk), process listing vs detail, service status vs logs vs restart, file operations (list, metadata, search, read), and git (status, diff, log). No two tools overlap in purpose, and descriptions clearly delineate when to use each.
All tool names follow a consistent verb_noun pattern in snake_case: get_cpu_usage, list_processes, get_service_logs, search_files, git_status, run_tests. The git_ prefix acts as a consistent namespace, and verbs (get, list, search, read, restart, run) are unambiguous.
With 18 tools, the set is slightly above the typical 3-15 sweet spot but still well-scoped for a system diagnostic server. The breadth (system, process, service, file, git, tests) justifies each tool's existence, and none feel redundant.
The surface covers monitoring and read-only inspection comprehensively, but notable mutating actions are missing: no process kill, no file write/edit, no git commit/push, and only restart_service (no start/stop). This limits full lifecycle management, though it may be intentional for a diagnostic tool.
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Secure Linux sandboxes for AI agents, as MCP tools.
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to perform controlled Linux system administration tasks like reading logs, managing services, cron jobs, WordPress, and executing sandboxed Python code, with strict security constraints.292GPL 2.0
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to diagnose Linux server incidents by collecting and structuring system diagnostics from multiple servers via SSH, with tools for finding incident clusters, gathering context (memory, CPU, swap, etc.), and running arbitrary commands.-
- AlicenseAqualityBmaintenanceLets an AI assistant inspect a Linux machine through ten fixed read-only tools covering load, memory, disks, processes, ports, interfaces, systemd units, the journal, and allowlisted log files. All output is size-capped, control-character-stripped and secret-redacted, and nothing in the package can write to the system.10MIT
- AlicenseAqualityBmaintenanceGives AI agents safe, bounded, non-blocking access to Linux sysadmin inspection tasks, including CPU, RAM and disk healthchecks, memory-safe log tailing with regex filtering, and user-level systemd service and timer auditing. All operations run without sudo or unrestricted root shells, avoiding interactive pager hangs and context window flooding.478 PyPI1MIT