Python CLI MCP Server for Local Apps

Overview

This project provides a lightweight Python MCP (Model Context Protocol) server that exposes local command-line applications to local apps and agents. It lets programs orchestrate, run, monitor and automate CLI workflows through an MCP-compliant interface, so tools or language models can interact with shell programs in a controlled, observable way.

The server is intended for local development and automation: you can run commands, stream output, capture exit codes, and enforce security policies (such as command allowlists, working directories and timeouts). This makes it easier to integrate existing CLI tools into higher-level automation, testing, or agent workflows without embedding shell logic directly into those systems.

Features

• Run arbitrary CLI commands and capture stdout/stderr and exit status
• Stream live output to clients so interactive or long-running jobs can be monitored
• Enforce security controls: command allowlists/deny-lists, working directory constraints, environment overrides, and timeouts
• Task management: start, list, inspect, and stop running commands
• Simple JSON-based request/response model compatible with MCP-style clients
• Lightweight Python implementation suitable for local or single-user setups
• CLI and Python client examples to help integrate with other tools

Installation / Configuration

Install directly from the GitHub repository or from a local copy:

# Install from GitHub
pip install git+https://github.com/ofek/pycli-mcp.git

# Or clone and install editable for development
git clone https://github.com/ofek/pycli-mcp.git
cd pycli-mcp
pip install -e .

Start the MCP server (example command; your installed entrypoint may vary):

# Start server on the default port (e.g. 8080)
pycli-mcp serve

# Or specify a port and config file
pycli-mcp serve --port 9090 --config ./mcp-config.yml

Example configuration (YAML) — adjust paths, command allowlist, timeouts and environment as needed:

# mcp-config.yml
server:
  host: 127.0.0.1
  port: 9090

security:
  allow_commands:
    - ls
    - git
    - python
  deny_commands: []
  allowed_workdirs:
    - /home/user/projects
  max_runtime_seconds: 300

environment:
  PATH: /usr/local/bin:/usr/bin:/bin

Common CLI management commands (after installing the package):

(Replace these examples with the actual entrypoint names if different in your installation.)

Available Resources

• Python client snippet: use the included Python helper or any HTTP client to talk to the server’s JSON endpoints.
• CLI client: lightweight wrapper to run commands through the server from the shell.
• Example config files: sample allowlist and environment configurations for common workflows.
• Logs and task metadata: the server exposes per-task metadata (pid, start time, exit code) and streamable logs for stdout/stderr.

Example: run a command with the Python client (HTTP-style pseudocode):

import requests
payload = {
    "command": ["python", "-m", "http.server", "8000"],
    "cwd": "/home/user/projects/myapp",
    "env": {"EXAMPLE": "1"}
}
r = requests.post("http://127.0.0.1:9090/run", json=payload, stream=True)
for chunk in r.iter_content(chunk_size=None):
    print(chunk.decode(), end="")

Adjust the endpoint path according to the server’s actual API (e.g., /run, /tasks, /stop).

Use Cases

• Automation for local development: script complex multi-step build or test flows and observe output in real time from editor plugins or local agents.
• Local AI agents: let a model-based agent execute and inspect CLI tools (linting, test runners, language-specific tooling) while restricting which commands it may run.
• Reproducible data transforms: programmatically run data-processing pipelines (CSV/JSON/CLI tools) and capture logs, outputs and exit codes for auditing.
• CI helpers and pre-commit automation: run guarded commands in a reproducible environment on developer machines before pushing changes.
• Monitoring long-running processes: start services or background tasks and stream their logs to a client for debugging.

Security and Best Practices

• Use allowlists (whitelists) to restrict the set of commands the server can run.
• Limit allowed working directories to prevent arbitrary filesystem access.
• Set reasonable timeouts and resource limits (CPU/memory if available) for untrusted workflows.
• Run the server as a single-user development service (avoid exposing to public networks) or put it behind an authenticated proxy when needed.

Next Steps

• Review the included sample configs and client examples to match the server to your workflow.
• Integrate the Python client into editor plugins, test runners, or agent frameworks to automate local CLI tasks.
• Extend policies around command validation and resource limits as your usage grows.