Linux MCP Server

A Python MCP server that exposes full Linux system control to AI clients (Claude Desktop, Claude Code, Cursor, Gemini CLI, etc.) over Streamable HTTP.

Features

• 9 MCP tools: bash_execute, read_file, write_file, edit_file, glob, grep, prepare_upload, prepare_download, server_overview (optional, requires the recorder module)

• Binary / large file transfer: bypass HTTP endpoints (PUT/GET /files/raw/{ticket}) for streaming uploads and downloads — file bytes never enter the LLM context window

• Per-token permissions: read-only (ro) or read-write (rw) roles

• Audit logging: JSON Lines audit trail with error details for all tool invocations

• Application logging: errors and warnings output to stderr (captured by journald)

• Protected paths: MCP's own files are protected from tool access

• Multi-user auth: Bearer token authentication with per-token management

• Admin API: create/revoke tokens without restarting the server

• Streamable HTTP transport: stateless mode, each request is independent (no session issues on reconnect)

Related MCP server: mcp-remote-agent

Requirements

• Python 3.11+

• ripgrep (rg) — optional but recommended for faster grep tool (falls back to Python regex)

Install

Requires Python 3.11+ on Linux.

pipx install algony-mymcp

The PyPI distribution name is algony-mymcp (the bare name mymcp is reserved on PyPI). After install the command and the Python import path are still plain mymcp.

Plain pip works too (a venv is recommended):

python3 -m venv ~/.local/share/mymcp-env
~/.local/share/mymcp-env/bin/pip install algony-mymcp
ln -s ~/.local/share/mymcp-env/bin/mymcp ~/.local/bin/mymcp

Quick try (foreground, no system service)

mymcp serve

mymcp prints a temporary admin and rw token to stderr, listens on 0.0.0.0:8765 by default, and discards both tokens on exit.

Production install (systemd)

sudo mymcp install-service --yes
sudo systemctl start mymcp

This writes /etc/mymcp/.env, generates an admin token (printed once), optionally generates a metrics token, installs /etc/systemd/system/mymcp.service, sets up logrotate for /var/log/mymcp/audit.log, and (by default) installs ripgrep for fast file search.

Useful flags: --port 9000, --bind 127.0.0.1, --config-dir, --log-dir, --service-user mymcp (run as a restricted user), --no-metrics, --no-audit, --skip-ripgrep.

Upgrade

pipx upgrade algony-mymcp
sudo systemctl restart mymcp

Backup and disaster recovery

See docs/operations/backup-and-disaster-recovery.md for what to back up (token store, audit log, recorder data, .env), restore procedures, and a failure-mode → response table.

Air-gapped install

Each GitHub Release ships a mymcp-X.Y.Z-offline-bundle.tar.gz containing all wheels and ripgrep binaries:

tar xzf mymcp-2.0.0-offline-bundle.tar.gz
cd mymcp-2.0.0-offline-bundle
sudo ./install-offline.sh
sudo mymcp install-service --yes

Why we don't ship a Dockerfile

mymcp's purpose is to let an LLM operate the host Linux system: install packages, edit config under /etc, manage processes, read/write files under /home. Running mymcp inside a container defeats this — by default the container sees only its own filesystem and PID namespace, so the LLM can only operate the container itself.

To make a containerised mymcp actually control the host you'd need at minimum --privileged --pid=host --net=host -v /:/host and a convention that the LLM works against /host. At that point the container provides no isolation; it's an awkward installer.

If you really want a container (e.g. as a sidecar that manages another containerised service), it is ~10 lines:

FROM python:3.13-slim
RUN pip install algony-mymcp
EXPOSE 8080
ENV MYMCP_HOST=0.0.0.0 MYMCP_PORT=8080
CMD ["mymcp", "serve"]

The recommended deployment is pipx install algony-mymcp + the shipped systemd unit (mymcp install-service), which gives the service direct host access matching the product's purpose.

Optional: server overview recorder

pip install algony-mymcp[recorder-anthropic] (or recorder-openai, or recorder for both) adds an asyncio module that maintains a self-updating server overview document via LLM. Disabled by default; enable with MYMCP_RECORDER_ENABLED=true. See docs/superpowers/specs/2026-05-29-llm-recorder-design.md for full details.

CLI Reference

Top-level commands

mymcp serve

mymcp serve --help

Important flags:

mymcp install-service

sudo mymcp install-service --help

Important flags:

mymcp uninstall-service

sudo mymcp uninstall-service --help

mymcp token

mymcp token --help

Subcommands:

mymcp doctor

Use this when install, Python path, rg, or env-file resolution looks wrong:

mymcp doctor

Configuration

mymcp install-service writes /etc/mymcp/.env. The serve command also honors --env-file PATH, MYMCP_ENV_FILE, and (in dev) ./.env.

Core

Audit Logging

Tool Limits

All limits are configurable via environment variables. Default values work well for most use cases.

Recorder (optional)

These only apply when the [recorder] / [recorder-anthropic] / [recorder-openai] extra is installed.

Managing Tokens

The mymcp token subcommands operate on the local token store directly (no admin API call required). They read /etc/mymcp/.env by default; use MYMCP_ENV_FILE=... to point elsewhere.

# List all tokens (admin/metrics state + ro/rw entries)
sudo mymcp token list

# Create a read-only token
sudo mymcp token add --name my-claude-desktop --role ro

# Create a read-write token
sudo mymcp token add --name my-admin-client --role rw

# Revoke
sudo mymcp token revoke tok_abc123

# Rotate the admin or metrics token (rewrites .env)
sudo mymcp token rotate-admin
sudo mymcp token rotate-metrics

# Disable the /metrics endpoint by emptying the metrics token
sudo mymcp token disable-metrics

The HTTP /admin/* API still works for clients that need to manage tokens remotely; it requires Authorization: Bearer <MYMCP_ADMIN_TOKEN>.

HTTP Endpoints

Public / operational endpoints

Examples:

curl http://your-server:8765/health
curl http://your-server:8765/version
curl -H "Authorization: Bearer $MYMCP_METRICS_TOKEN" \
  http://your-server:8765/metrics

Notes:

• /metrics returns 401 if the bearer token is wrong.

• /metrics returns 503 if metrics support is disabled or no metrics token is configured.

Admin API

All /admin/* endpoints require:

Authorization: Bearer <MYMCP_ADMIN_TOKEN>

Examples:

# List tokens
curl -H "Authorization: Bearer $MYMCP_ADMIN_TOKEN" \
  http://your-server:8765/admin/tokens

# Create a read-only token
curl -X POST \
  -H "Authorization: Bearer $MYMCP_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-bot","role":"ro"}' \
  http://your-server:8765/admin/tokens

# Revoke a token
curl -X DELETE \
  -H "Authorization: Bearer $MYMCP_ADMIN_TOKEN" \
  http://your-server:8765/admin/tokens/tok_abc123

Connecting Clients

Claude Desktop / Cursor

Add to MCP settings:

{
  "mcpServers": {
    "linux-server": {
      "type": "streamableHttp",
      "url": "http://your-server:8765/mcp",
      "headers": {
        "Authorization": "Bearer tok_abc123"
      }
    }
  }
}

Claude Code

claude mcp add linux-server \
  --transport streamable-http \
  --url http://your-server:8765/mcp \
  --header "Authorization: Bearer tok_abc123"

MCP Tools

Permission model

ro tokens can use read_file, glob, grep, prepare_download, and server_overview. rw tokens can use all nine tools.

bash_execute (rw)

Runs a shell command in a new subprocess. Commands are stateless: one call does not preserve cwd, environment changes, shell functions, or exports for the next.

Parameters:

Returns:

• stdout

• stderr

• exit_code

• timed_out

Example:

{
  "command": "uname -a",
  "timeout": 10,
  "working_dir": "/tmp"
}

read_file (ro)

Reads a file and returns numbered lines. Large reads support pagination.

Parameters:

Returns:

• content

• total_lines

• truncated

Common errors:

• FileNotFoundError

• IsADirectoryError

• PermissionError

• ProtectedPath

Example:

{
  "file_path": "/var/log/syslog",
  "offset": 1,
  "limit": 200
}

write_file (rw)

Creates or overwrites a file in one shot.

Parameters:

Notes:

• Missing parent directories are created automatically.

• Protected paths are rejected.

Example:

{
  "file_path": "/tmp/hello.txt",
  "content": "hello from mymcp\n"
}

edit_file (rw)

Replaces text in an existing file.

Parameters:

Use this when the client wants a precise in-file replacement instead of full overwrite.

Example:

{
  "file_path": "/tmp/app.conf",
  "old_string": "PORT=8000",
  "new_string": "PORT=8765"
}

glob (ro)

Finds matching files under a root directory. Results are sorted by modified time descending.

Parameters:

Runtime max results: 1000.

Example:

{
  "pattern": "**/*.log",
  "path": "/var/log"
}

grep (ro)

Searches file contents with a regex. Uses ripgrep if available; otherwise falls back to a Python implementation.

Parameters:

Example:

{
  "pattern": "Authorization",
  "path": "/etc",
  "glob": "*.conf",
  "output_mode": "content",
  "context_lines": 2
}

prepare_upload (rw) and prepare_download (ro)

Use for binary files or files larger than 10 MB that don't need to be read into the conversation. The MCP tool only returns a small JSON object containing a one-time signed URL — the actual file bytes never enter the LLM context window. The client then drives the byte transfer with a regular curl from its local shell.

Workflow:

1. LLM calls prepare_upload(dest_path="/tmp/foo.deb", max_bytes=20_000_000) → server returns a JSON dict with url, method: "PUT", expires_in (default 300 s), max_bytes, and a ready-to-run curl_example like curl -fsS -T /local/path/to/file 'https://server/files/raw/<ticket>'.

2. LLM (or the user) runs the curl on the MCP client's local shell. Bytes stream straight to the server — no MCP message, no base64.

3. Server writes to a temp file alongside the destination, atomically replaces it on success, and returns {"ok": true, "path": "...", "bytes_written": N}.

prepare_download is the mirror: it returns a GET URL, you curl URL -o local, and bytes stream back.

Tickets are single-use, path-scoped, byte-bounded, and expire after expires_in seconds (default 300, max 900). Both endpoints reuse the same check_protected_path and audit log as the file tools. Server tunables: MYMCP_TRANSFER_ENABLED, MYMCP_TRANSFER_MAX_BYTES (default 2 GB), MYMCP_TRANSFER_DEFAULT_TTL_SEC, MYMCP_TRANSFER_MAX_TTL_SEC, MYMCP_PUBLIC_BASE_URL (set when behind a reverse proxy).

server_overview (ro)

Returns the current contents of the server overview document maintained by the optional recorder module. Only available when the recorder is installed and MYMCP_RECORDER_ENABLED=true; otherwise the call fails with a clear error message. Takes no parameters.

The recorder periodically folds successful mutating audit events into an overview of what's installed and recently changed on the host. The companion changelog.md in the same directory can be read with read_file. See the "Optional: server overview recorder" section above for setup; full design details are in docs/superpowers/specs/2026-05-29-llm-recorder-design.md.

Tool behavior notes

• File tools enforce protected-path checks.

• bash_execute does not enforce protected-path checks; use ro tokens for untrusted clients.

• grep and glob are capped to protect the server from unbounded scans.

• read_file truncates oversized individual lines and marks them with [LINE TRUNCATED].

• prepare_upload/prepare_download enforce protected-path checks at both mint and redeem time.

Logging

Audit Log

When enabled (MYMCP_AUDIT_ENABLED=true), all tool invocations are logged to <MYMCP_AUDIT_LOG_DIR>/audit.log in JSON Lines format:

{"ts":"2026-04-10T15:30:22Z","token_name":"my-client","role":"rw","ip":"203.0.113.5","tool":"bash_execute","params":{"command":"apt update"},"result":"ok","duration_ms":1523}

Error entries include error_code and error_message:

{"ts":"2026-04-10T15:31:00Z","token_name":"ro-client","role":"ro","ip":"203.0.113.5","tool":"read_file","params":{"file_path":"/var/log/mymcp/audit.log"},"result":"error","error_code":"ProtectedPath","error_message":"Access denied: path is within protected directory","duration_ms":0}

Logs rotate automatically (default 10MB with 5 backups).

Application Log

Tool errors and warnings are also output to stderr, which is captured by journald when running as a systemd service:

journalctl -u mymcp -f

Protected Paths

MCP automatically protects its own installation directory and audit log directory from access via file tools (read_file, write_file, edit_file, glob, grep). This prevents AI clients from reading tokens, modifying server code, or tampering with audit logs.

Add extra protected paths via MYMCP_PROTECTED_PATHS=/path/one,/path/two.

Note: bash_execute is not subject to path protection — use ro tokens for untrusted clients.

Observability

mymcp emits metrics, traces, and logs via OpenTelemetry. The default install supports Prometheus pull at /metrics; the [otlp] extra adds OTLP push for any backend.

Quick reference

Recipe 1 — Grafana Cloud (free tier)

pip install algony-mymcp[otlp]

export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-us-central-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64(instanceId:token)>"
export OTEL_SERVICE_NAME=mymcp

mymcp serve

Import deploy/grafana/mymcp-dashboard.json (metrics, incl. the Recorder Health row) and deploy/grafana/mymcp-logs-dashboard.json (Loki+Tempo) into Grafana Cloud.

Recipe 2 — Self-hosted LGTM stack

docker-compose.yml:

services:
  collector:
    image: otel/opentelemetry-collector-contrib:latest
    ports: ["4318:4318"]
    volumes: ["./otelcol-config.yaml:/etc/otelcol-contrib/config.yaml"]
  mimir:
    image: grafana/mimir:latest
    command: -config.file=/etc/mimir.yaml
  loki:
    image: grafana/loki:latest
  tempo:
    image: grafana/tempo:latest
  grafana:
    image: grafana/grafana:latest
    ports: ["3000:3000"]

Then run mymcp with:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 mymcp serve

Import the dashboard JSON; configure Mimir/Loki/Tempo as data sources.

Recipe 3 — Pull-only Prometheus

No extra needed. Configure Prometheus:

scrape_configs:
  - job_name: mymcp
    bearer_token: <your MYMCP_METRICS_TOKEN>
    static_configs:
      - targets: ['localhost:8000']

Import the dashboard JSON; the Traces and Logs panels remain empty (this is expected).

Audit log integrity

Silent audit loss is a SOC red line, so the Grafana dashboard ships an Audit Log Integrity row (cumulative + per-second-rate panels). The project does NOT ship alert rules — alerting is deployment-specific. Recommended PromQL recipe for operators:

rate(mymcp_audit_write_failures_total[5m]) > 0

Recorder metrics ([recorder] extra)

When the recorder is enabled, these extra series appear on /metrics:

Recommended stale-recorder query (project ships metrics and dashboards only; alert rules are deployment-specific and not bundled):

( mymcp_recorder_pending_events > 0
  AND time() - mymcp_recorder_merge_last_attempt_timestamp > 1800 )
OR mymcp_recorder_circuit_open == 1

Both terms together avoid the historical false positive where an idle server (no events to process) appeared "stale" because the success-timestamp gauge hadn't moved.

The Grafana metrics dashboard's Recorder Health row materialises all of the above. The supervisor's per-tick work runs inside a recorder.supervisor.cycle span so recorder.supervisor.cycle_error log lines carry the matching trace_id/span_id for jumping into Tempo from Loki.

Configuration knobs

All standard OTel env vars work. The most useful:

Testing

# Run all tests (excludes benchmarks)
python -m pytest tests/ -v --benchmark-disable

# Run with coverage report
python -m pytest tests/ -v --cov=. --cov-branch --cov-report=term-missing --benchmark-disable

# Run benchmark tests only
python -m pytest tests/test_benchmark.py --benchmark-only -v

# Save benchmark baseline for comparison
python -m pytest tests/test_benchmark.py --benchmark-save=baseline

# Run mutation testing
python -m mutmut run --max-children 1
python -m mutmut results

# Run load tests (start server first: mymcp serve)
export MYMCP_TEST_TOKEN=<your-rw-token>
locust -f tests/loadtest/locustfile.py --host http://localhost:8765

Test Dimensions

Security Note

This server grants system access to AI clients. Security measures:

• Permissions: New tokens default to ro (read-only). Only grant rw to trusted clients.

• Audit: Enable audit logging to track all tool invocations.

• Protected paths: Server files are automatically protected from tool access.

• Network: Run behind a firewall and consider TLS (e.g. via nginx reverse proxy).