Advertise
MCP.so
Sign In

mcp-shell MCP Server

@sonirico

Repository

Basic information

Category

Developer Tools

License

GPL-3.0

Transports

stdio

Author

sonirico

About mcp-shell MCP Server

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

mcp-shell MCP Server 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"
      ]
    }
  }
}

mcp-shell MCP Server tools

Tool list not available yet

This listing does not currently have a tool list to display. This does not mean the server has no tools; check its documentation for supported capabilities.

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.

Frequently asked questions

1

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.

2

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.

3

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.

4

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.

5

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

More Developer Tools MCP servers

Crawl Readiness

Grubbomatic

AI SEO tools for MCP clients — audit whether AI crawlers can read a website, validate JSON-LD and robots.txt, and generate llms.txt, AI-crawler-aware robots.txt, and JSON-LD schema without leaving the conversation.

Layro

Layro

Layro connects your AI coding tool (Cursor, Claude Code, VS Code, Windsurf, Codex, Gemini CLI) to 112 production React, TypeScript and Tailwind CSS components. Your agent can search the library, read each component's pro

Final POS – Custom POS Builder

Final Commerce

Build custom POS apps with your AI agent. Final's MCP server lets developers scaffold checkout flows, adapt vetted screen blueprints for counter POS, self-checkout kiosks, restaurant ordering and payment terminals, previ

Cronwatch

cronwatchdev

CronWatch records every run of your scheduled jobs in your own database, and speaks up when one is missed, fails, gets stuck, runs slow or costs too much. CronWatch is free and open-source.

31

Sazabi

Sazabi

Give your coding agent access to production. Search your logs in plain language, look up issues and investigate errors from Claude Code, Cursor, Codex or ChatGPT. Requires a Sazabi account; sign in with OAuth.

Advertise