mcp-shell 🐚

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.