mcp-shell 🐚

@sonirico

About mcp-shell 🐚

Give hands to AI. MCP server to run shell commands securely, auditably, and on demand.

#go #shell #bash #terminal #ai #mcp #llm #model-context-protocol #os-exec

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "mcp-shell": {
      "command": "docker",
      "args": [
        "run",
        "-it",
        "--rm",
        "-v",
        "/tmp/mcp-workspace:/tmp/mcp-workspace",
        "sonirico/mcp-shell:latest"
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is mcp-shell?

mcp-shell is an MCP server that runs shell commands, giving an LLM a tool while keeping control over what commands execute and how. Written in Go and built on mark3labs/mcp-go.

How to use mcp-shell?

Run via Docker (docker run -it --rm -v /tmp/mcp-workspace:/tmp/mcp-workspace sonirico/mcp-shell:latest) or from source (git clone, make install, then mcp-shell). Default is secure mode; customize with a YAML config file pointed to by MCP_SHELL_SEC_CONFIG_FILE. Wire into Claude Desktop by adding a shell server entry in its MCP config pointing to the Docker image or binary.

Key features of mcp-shell

Executes shell commands as an MCP tool.
Secure default mode with a strict executable allowlist (read‑only utilities).
Configurable YAML policy for both secure and legacy shell‑execution modes.
Docker deployment as a non‑root Alpine image.
Tool response includes exit code, stdout, stderr, execution time, and security info.
Audit logging and configurable timeouts and output size limits.

Use cases of mcp-shell

LLM agents perform read‑only file operations (list, cat, grep) in a controlled workspace.
Running approved system tasks under user‑defined command policies.
Integrating shell execution into AI workflows with audited, sandboxed commands.
Debugging or inspecting system state via an LLM interface.

FAQ from mcp-shell

What is the default security mode?

Secure mode is the default, restricting execution to a narrow allowlist of read‑only utilities (ls, cat, grep, find, head, tail, …). No shell interpretation or interpreters are allowed.

How do I run unrestricted commands?

Set the environment variable MCP_SHELL_ALLOW_UNSAFE=true before starting the server. This disables all validation and is not recommended for production.

How do I customize the security policy?

Create a YAML config file and set MCP_SHELL_SEC_CONFIG_FILE to its path. You can enable secure or legacy mode, define allowed executables/commands, blocked patterns, timeouts, and output limits.

What happens if I allow an interpreter like bash?

The server warns at startup and denies the command. Interpreters execute whatever they are handed, bypassing secure mode, so they are hard‑denied even if on the allowlist.

How does the tool API work?

Pass a command string (required) and optional base64 boolean. The response includes status, exit_code, stdout, stderr, command, execution_time, and optional security_info. Uses exec.Command in secure mode.

Frequently asked questions

What is the default security mode?

Secure mode is the default, restricting execution to a narrow allowlist of read‑only utilities (`ls`, `cat`, `grep`, `find`, `head`, `tail`, …). No shell interpretation or interpreters are allowed.

How do I run unrestricted commands?

Set the environment variable `MCP_SHELL_ALLOW_UNSAFE=true` before starting the server. This disables all validation and is not recommended for production.

How do I customize the security policy?

Create a YAML config file and set `MCP_SHELL_SEC_CONFIG_FILE` to its path. You can enable secure or legacy mode, define allowed executables/commands, blocked patterns, timeouts, and output limits.

What happens if I allow an interpreter like bash?

The server warns at startup and denies the command. Interpreters execute whatever they are handed, bypassing secure mode, so they are hard‑denied even if on the allowlist.

How does the tool API work?

Pass a `command` string (required) and optional `base64` boolean. The response includes `status`, `exit_code`, `stdout`, `stderr`, `command`, `execution_time`, and optional `security_info`. Uses `exec.Command` in secure mode.

Comments

Basic information

More Developer Tools MCP servers

Air Pipe

airpipe

Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.

extentos

Asger mølgaard

Extentos is a multi-vendor development platform for adding smart-glasses capabilities to existing iOS and Android apps. The simplest analogy is Stripe for smart glasses:

PuzzleTide Puzzle Generator

Caravaca-Labs

Word search generator, crossword generator, and sudoku generator + solver as a local-first MCP server. 15 deterministic tools: printable PDF puzzle worksheets, themed word banks, and verifiable LLM evals. From the makers

endoflife.ai

Free MCP server for software end-of-life intelligence: EOL dates, support status, and the 0-100 EOL Risk Score across 480+ tracked products. Agents can check a single version, pull a product's full lifecycle schedule, or

Unity MCP (Server + Plugin)

IvanMurzak

AI Skills, MCP Tools, and CLI for Unity Engine. Full AI develop and test loop. Use cli for quick setup. Efficient token usage, advanced tools. Any C# method may be turned into a tool by a single line. Works with Claude Code, Gemini, Copilot, Cursor and any other absolutely for fr

3.5K