Overview

This MCP (Model Context Protocol) server provides a compact, developer-focused way to inspect and terminate operating system processes via natural-language queries. It exposes a small API that can be integrated with local LLM agents or other tooling that speaks MCP, so you can ask—using plain language—to find offending processes and stop them quickly and securely.

The server is useful when you need a programmatic, auditable way to manage processes from CI runners, remote developer tools, or AI assistants that are able to reason about system state. Instead of manually searching by PID or command line, you can issue descriptive queries (for example, “kill the longest-running Python process started by user alice”) and let the MCP-enabled tooling resolve the correct process and perform the action.

Features

List active OS processes with useful metadata (PID, user, CPU, memory, command line, start time).
Terminate processes by PID or by natural-language query resolved by the MCP agent.
Simple JSON HTTP API suitable for automation and MCP integration.
Authentication support (token-based) to restrict who can query or terminate processes.
Optional Docker support for consistent deployment.
Audit-friendly responses and explicit result reporting after kill attempts.

Installation / Configuration

Below are general setup examples. Adjust to your platform and follow the repository README for language-specific instructions.

Clone the repository:

git clone https://github.com/misiektoja/kill-process-mcp.git
cd kill-process-mcp

Run locally (example patterns — adapt to the actual runtime in the repo):

# If the project is a Node app
npm install
npm start

# Or if it's a Python app
pip install -r requirements.txt
python app.py

Docker (build and run):

docker build -t kill-process-mcp .
docker run -p 8080:8080 \
  -e MCP_AUTH_TOKEN="your-secret-token" \
  --cap-add=SYS_PTRACE \   # if required for extended process info
  kill-process-mcp

Environment variables (common examples):

# Port where the server listens
PORT=8080

# Token used by clients and MCP agents to authenticate
MCP_AUTH_TOKEN=replace_with_secure_token

# Optional: enable verbose logging
LOG_LEVEL=info

Available Tools / Resources

The server exposes a minimal set of HTTP endpoints suitable for automation or integration with MCP-capable agents.

Example endpoints:

GET /processes

Returns a list of running processes.
Query parameters: sort (cpu|mem|time), limit, user.

Example response (JSON):

[
  {
    "pid": 1234,
    "user": "alice",
    "cpu_percent": 12.5,
    "memory_mb": 128,
    "cmd": "/usr/bin/python3 server.py --port 8000",
    "start_time": "2026-04-01T12:23:34Z"
  }
]

POST /kill
- Terminates a process. Accepts either a PID or a natural-language query.
- Payload examples:
```
{ "pid": 1234 }
```
  or
```
{ "query": "the node process using most CPU" }
```
- Response includes success/failure, signal used, and a short reason.

Authentication

Add header: Authorization: Bearer <MCP_AUTH_TOKEN>

Process fields (table):

Field	Description
pid	Process identifier (integer)
user	Owner of the process
cpu_percent	CPU usage percentage
memory_mb	Resident memory in MB
cmd	Full command line
start_time	ISO-8601 start timestamp

Use Cases

Kill a runaway process by PID

Use case: CI job spawns a job that doesn’t terminate.

Example:

curl -X POST http://localhost:8080/kill \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pid": 4321}'

Kill a process using a natural-language query
- Use case: You remember the process by description, not PID.
- Example:
```
curl -X POST http://localhost:8080/kill \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "kill the python process consuming the most CPU"}'
```
- The server (or MCP agent tied to it) resolves the query to a PID, returns the intended target for confirmation, then performs the termination.

Inspect processes before acting

Use case: Audit and verification prior to any kill.

Example:

curl -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  http://localhost:8080/processes?sort=cpu&limit=10

Integrate with an LLM-based operator
- Use case: Add process management capability to an assistant that can safely request process termination when necessary. The MCP protocol lets the assistant query the process list and request kills using human language, while the server enforces auth and returns structured results.

Security and Best Practices

Always protect the server with a strong authentication token and network-level controls (firewalls, local-only binding when appropriate).
Prefer read-only listing for less-privileged workflows; require stricter auth for /kill.
Log every kill request with requester identity and reason to maintain audit trails.
Use dry-run or confirm modes in automated agents to avoid accidental termination.
Run the server with least privilege; avoid running as root unless required.

Where to find the project

Source and issues: https://github.com/misiektoja/kill-process-mcp

For detailed runtime

MCP Server: List and Terminate Processes