cmdshellmcp
command shell mcp server with additional tools (e.g. for coding)
Install / Use
claude mcp add ag88 -- npx -y github:ag88/cmdshellmcpIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
Tags
Our assessment of cmdshellmcp
cmdshellmcp scores 80/100 on our quality scale, 746th of 957 AI & Machine Learning skills we index.
Its MCP Server is 34 KB long, well organised into 40 sections with 30 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 31 days ago, so cmdshellmcp is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 87/100, with 2 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-16. Automated pattern scan on 2026-11-16. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
cmdshellmcp compared with similar skills
All 4 of these similar skills score higher than cmdshellmcp; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| cmdshellmcp (this skill)by ag88 | 80 | 3 | 31d ago | MCP Server |
| claude-memby thedotmack | 100 | 117.7k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.4k | 9d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.9k | 1d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install cmdshellmcp?
- Run
claude mcp add ag88 -- npx -y github:ag88/cmdshellmcp. The install tabs above show the steps for each supported agent. - Which AI agents does cmdshellmcp work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is cmdshellmcp safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 87/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is cmdshellmcp still maintained?
- The repository was last updated 31 days ago, so cmdshellmcp is actively maintained.
Skill content
View source on GitHubcmdshellmcp
cmdshellmcp is a constrained command-shell MCP server for AI agents. It exposes a small allowlisted Unix command set, somewhat safe file operations, patch application, and URL fetching so an MCP client can perform limited local tasks without unrestricted shell access.
The server is implemented in Python and runs as an MCP server using the fastmcp package. By default it listens on 127.0.0.1:8003 using the streamable HTTP transport unless --sse is selected.
Added setup files for a full featured Docker Debian based sandbox system container with cmdshellmcp (setup scripts, guides DOCKER.md, Dockerfile, cmdshellmcp.service unit file that runs cmdshellmcp in the container).
[!CAUTION]
This server provides remote command execution (RCE), which is normally considered a critical security vulnerability. Allow-listing powerful commands—such as bash, sh, python, perl, sudo, docker, or commands capable of writing files—may allow an attacker or untrusted LLM to bypass intended restrictions and take control of the system. For example, allowing python or bash can effectively permit arbitrary code execution and file access. If the server lacks strong authentication, is reachable by untrusted clients, or is controlled by an untrusted or prompt-injected LLM, it may cause severe damage, including data loss, credential theft, malware installation, or compromise of other systems. Run cmdshellmcp (cmdshellmcp2.py) only in a protected, disposable sandbox with carefully scoped privileges limited to those required for its intended task and limited access to files, credentials, devices, and networks—for example, disposable Docker container or virtual machine that can be safely destroyed after use.
Warning
This is a scratch / experimental app that evolved out of using an MCP server (tools) that allow running shell commands for coding purpose. Unfortunately, for such a purpose, one often needs to provide the LLM (model) client with rather powerful shell commands to "do its job" for a particular scope / context / intent.
The default allowed commands are not necessarily safe, i.e. LLM agents or practically clients calling
the MCP api can 'escape' and do things outside a context e.g. the working directory defined with --cwd
option. It validates the arguments in a limited way, i.e. looking for string path patterns if they seem to escape the current
directory. This is a heuristic check, i.e. this check is pattern matching, it does not know if that argument is intended to be a file
or directory. Nor does it know the argument's context for a particular command, or if they are after all safe.
e.g. it may prevent a ls / (listing a root directory), but sometimes that is what you need. But it may prevent by sheer pattern
matching e.g. rm /PreciousFile.txt i.e. remove a file in the root directory. This is not an always secure check, but added
as it is better than no checks at all.
There are also tools (MCP functions exposed) that expose write and file modification ops, including executing shell commands.
- Authentication is enabled by default. Keep the randomly generated token, or set
a fixed auth_token using the auth field in the config file or
--auth. Using--noauthpractically means you are giving remote command execution (RCE) to any (including possibly malicious or rogue) clients that can reach the server. - Run this as an unprivileged user. Running as
rootis at best foolish - Do not use this with untrusted clients or untrusted LLMs
- Use it in a disposable sandbox e.g. a standalone docker container or virtual machine that you can afford to throw away including the contents
- Review the allow list in
cmdshellmcp.jsonand the hardcoded defaults, revise them before using.
Features
- Allowlisted shell execution for a curated set of commands
- File read/write/list/copy/move/rename/delete operations and basic directory creation/removal under a configured working directory
- Transactional text-file editing with
sed, numbered backups, and unified diffs - Unified diff patch application via
patch - HTTP fetch support with optional HTML prettification
- Bearer token authentication with a secure, randomly generated token by default
- Audit logging to stdout and/or a file
- Path restrictions to prevent escaping the current working directory
- Setup files for a delightful, full featured Docker Debian based sandbox system container with
cmdshellmcp(setup scripts, guides DOCKER.md, Dockerfile,cmdshellmcp.serviceunit file that runscmdshellmcpin the container).
AI use in this repo
This app and its contents e.g. this page, is created with the aid of LLM (large language models) such as
- ChatGPT 5.6 sol (light), Codex
- Github Co-pilot MAI-Code-1.1-Flash
Initial codes is written by the author and refactored with aid of the LLMs and updates is also done partly manually. After features are added or changed, additional tests is often done by manually running them e.g. in llama.cpp's llama-server Web UI
Installation
- Clone the repository.
- Create and activate a virtual environment if desired.
- Install dependencies:
python -m venv .venv
source .venv/bin/activate
pip install fastmcp requests beautifulsoup4
If your environment uses a requirements.txt, you can also install from there:
pip install -r requirements.txt
The editFile tool also requires GNU sed (including its --sandbox option)
and diff to be installed on the server. These programs are invoked directly by
the dedicated tool and do not need to appear in allowed_commands.
Configuration
A configuration file is mandatory. The server selects one JSON file in this order (files are not merged):
- The file specified by
--conf, when given (no automatic search). /etc/cmdshellmcp.d/cmdshellmcp.json./usr/local/python/cmdshellmcp/cmdshellmcp.json.
The current directory is never searched automatically. If no config is found,
startup exits with an error suggesting --conf FILE. A missing explicit file,
unreadable file, or invalid selected JSON file also fails startup. Command-line
options override their configuration keys; omitted optional settings retain
internal defaults within the required configuration.
Example:
{
"host": "127.0.0.1",
"port": 8003,
"cwd": "/path/to/project",
"shellnopathchk": false,
"editdelbk": false,
"quiet": false,
"auditlog": null,
"disableTools": ["writeFile", "editFile", "applyPatch", "copyFile", "moveRenameFile", "deleteFile", "mkdir", "rmdir"],
"allowed_commands": [
"ls", "pwd", "date", "cat", "grep", "egrep",
"whoami", "head", "tail", "sed", "wc", "file", "du", "df",
"free", "ps", "uname", "hostname", "uptime", "w", "last",
"mkdir", "cp", "mv", "awk"
],
"auth": "_my_secret_auth_token_"
}
Supported configuration keys:
host: bind host; default127.0.0.1port: bind port; default8003cwd: working directory path; required unless--cwdis suppliedshellnopathchk: boolean; bypasses shell argument path checks whentrue; defaultfalseeditdelbk: boolean; deletes successful edit backups after composing the diff whentrue; defaultfalsequiet: suppresses audit output to stdout whentrueauditlog: optional path to an audit log fileallowed_commands: list of commands permitted for executiondisableTools: list of MCP tool names to omit from the server, case sensitive and exact name match is requiredauth: optional fixed bearer token string; when omitted, a random token is generated at startup
Running the server
Start with an explicit configuration and working directory:
python cmdshellmcp2.py --conf /path/to/cmdshellmcp.json --cwd /path/to/project
If the config is installed in a default search location and supplies cwd,
python cmdshellmcp2.py is sufficient. Startup fails when neither --cwd nor
config cwd supplies a directory. There is no prompt or automatic working
directory fallback. The selected directory is logged before the server starts.
By default, the server listens on 127.0.0.1:8003 using streamable HTTP.
The following examples assume a config is installed in a default search location;
otherwise add --conf FILE. Supply --cwd PATH if the config leaves cwd unset.
SSE mode
python cmdshellmcp2.py --sse
This runs the server on the SSE transport instead of streamable HTTP.
Browser clients and CORS
Both HTTP transports include CORS middleware for browser-based MCP clients. The
server accepts requests from any origin, supports the MCP GET, POST, and
DELETE methods and browser preflight OPTIONS requests, and exposes the
mcp-session-id response header to browser JavaScript.
Because all origins are allowed, do not expose the server to an untrusted
network without authentication and appropriate network controls. To restrict
browser access, replace allow_origins=["*"] in CORS_MIDDLEWARE with the
specific trusted origins.
Custom working directory
python cmdshellmcp2.py --cwd /path/to/project
This overrides config cwd for file and shell tools. A configuration file is still required.
The path must exist and must be a directory; ~ is expanded and the selected
path is normalized to an absolute path.
Custom host and port
python cmdshellmcp2.py --host 0.0.0.0 --port 9000
Authentication
Authentication is enabled by default. If neither --auth nor an auth value in
the configuration file supplies a fixed token, the server generates a
cryptographically secure, base64-encoded token and displays it in the startup
log. The generated token is shown in bold when stdout supports ANSI styling.
Configure the MCP client to send that value as its bearer token.
To use a fixed token instead:
python cmdshellmcp2.py --auth my-secret-token
To explicitly run without authentication:
python cmdshellmcp2.py --noauth
--auth and --noauth are mutually exclusive. --noauth also overrides an
auth value in the configuration file. Disabling authentication is unsafe on
any network that is not completely trusted.
Audit logging
python cmdshellmcp2.py --quiet --auditlog /tmp/cmdshellmcp.log
--quietdisables audit logging to stdout.--auditlogappends audit events to the specified file.
A full featured Docker Debian based sandbox system container with cmdshellmcp
This project provides setup files for a delightful, full featured Docker Debian based sandbox system container with cmdshellmcp (setup scripts, guides DOCKER.md, Dockerfile, cmdshellmcp.service unit file that runs cmdshellmcp in the container).
Using the docker sandbox container gives you a "system in a system" experience, e.g. that Debian boots up within the container just like a full Unix / Linux system. It gives you 3 userids within the container:
root: (superuser)admin(this is for you / human user),adminhassudoaccess, i.e. practically can do anythingrootdoes, install files, change system configs, permissions etccodeagent:cmdshellmcpruns under this user, in the user's/home/codeagenthome directory.codeagenthas no sudo access.
For more details review DOCKER.md
Command-line options
python cmdshellmcp2.py [--cwd PATH] [--host HOST] [--port PORT] \
[--allow COMMAND [COMMAND ...]] [--conf FILE] [--auth TOKEN | --noauth] \
[--disableTools TOOL[,TOOL...]] [--editdelbk] [--shellnopathchk] [--sse] [--quiet] \
[--auditlog FILE] [--stdio]
Options:
--cwd: working directory used for file and shell operations; when omitted, use configcwd, otherwise exit with a missing working directory error--host: server bind host--port: server bind port- `--
Truncated for display — read the full file on GitHub.
Related Skills
claude-mem
117.7kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
112.4kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
92.9kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
