🛠️ mcp-micro-shell

An ultra-lightweight, secure, and high-performance MCP server providing isolated file operations and shell execution capabilities.

Fully optimized with a flat python layout, powered by uv, and ready for global execution via uvx.

🌟 Key Features

• ⚡ Lightning Fast Startup: Built entirely with a simplified flat package structure, executing instantly with uv virtual environments.
• 🛡️ Hardened Sandboxed Security: All terminal runs and file read/writes are strictly sandboxed inside your designated workspace directory (MCP_MICRO_SHELL_WORKSPACE), robustly defending against directory traversal (../) attacks.
• 🔌 Multi-Transport System:
  • Stdio (Default): High-speed JSON-RPC stdio transport for local desktop clients (Cursor, Claude Desktop, cl0w, etc.).
  • SSE (Server-Sent Events): High-performance SSE HTTP server using Starlette and Uvicorn for remote connections.
• ⚙️ Zero Stdout Pollution: Redirects all internal engine logs exclusively to stderr, keeping the stdout channel completely pristine for JSON-RPC messages.

📂 Simplified Architecture

Optimized down to a minimalist, highly cohesive Python package layout:

mcp-micro-shell/
├── pyproject.toml              # Build backend configuration (Hatchling)
├── README.md                   # English Documentation
├── README.ko.md                # Korean Documentation
├── uv.lock                     # Lock file
└── mcp_micro_shell/            # Primary python package
    ├── __init__.py             # Version declaration
    ├── __main__.py            # Module runner (python -m)
    └── server.py              # Unified server engine & tool bindings

🛠️ Provided Tools

All tools automatically resolve relative paths against the designated workspace root and validate boundaries.

| Tool Name | Parameters | Description | | :--- | :--- | :--- | | execute_command | command (str, req),
cwd (str, opt),
timeout (int, opt) | Safely executes terminal commands inside the workspace (or a sub-folder inside it). Inherits system PATH for full CLI tool access. | | get_current_directory | None | Returns the active workspace path boundary. | | read_file | path (str, req) | Reads text files safely, verifying boundary constraints. Blocks out-of-boundary paths. | | write_file | path (str, req),
content (str, req) | Writes text files safely, auto-creating subfolders inside the workspace boundary. Blocks out-of-boundary paths. |

🚀 Getting Started

Installation

You can install and run the server globally from PyPI using uv:

# Install globally
uv tool install mcp-micro-shell

# Or run instantly without installation
uvx mcp-micro-shell

Prerequisites

Make sure you have uv installed. If you don't, run:

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

🏃 Running the Server

1. Stdio Mode (Default)

Ideal for standard JSON-RPC desktop AI integrations.

uvx mcp-micro-shell

(For local development in the cloned repository, you can use uv run mcp-micro-shell instead).

2. SSE Mode (Web API)

Ideal for remote integrations. Runs an HTTP SSE server.

uvx mcp-micro-shell --transport sse --host 127.0.0.1 --port 8000

🔌 Integrating with MCP Clients (mcp.json)

To use this server inside AI clients (like Claude Desktop, Cursor, cl0w), configure your client config as follows:

{
  "mcpServers": {
    "mcp-micro-shell": {
      "command": "uvx",
      "args": [
        "mcp-micro-shell"
      ],
      "env": {
        "MCP_MICRO_SHELL_WORKSPACE": "C:\\path\\to\\your\\workspace"
      }
    }
  }
}

(No need to clone or point to local directories. uvx will automatically download, update, and launch the server directly from PyPI).