cmdxray — Claude Code MCP server: shell command breakdown and risk check
An offline MCP server that breaks a shell command into tokens and flags the destructive parts before an agent runs it.
claude mcp add cmdxray -- npx -y cmdxrayWhat cmdxray does
Hand cmdxray a command line and it returns an annotated breakdown: what each flag does, where a pipe sends output, what a redirect overwrites. A separate risk pass catches curl … | bash, rm -rf /, dd of=/dev/…, mkfs, chmod 777, git push --force, git reset --hard and sudo. Ordinary safe commands stay quiet, so a warning actually means something.
The danger engine also ships as cmdxray lint, which scans files — shell scripts, Dockerfiles, run: steps in CI YAML, Makefiles, git hooks — and reports findings in file:line form. It exits 1 on a DANGER, which makes it usable as a CI or pre-commit gate; --strict, --exit-zero and --json change the output. For interactive shells there is cmdxray guard: one line, eval "$(cmdxray guard bash)", in ~/.bashrc, and the shell asks for confirmation right before a destructive command fires.
The scan is heuristic and line-oriented rather than a full shell parser. A finding usually points at something genuinely risky, but a cleverly built command can slip past. Everything runs locally, so nothing leaves the machine.
What it helps with
- understand an unfamiliar command flag by flag
- check a one-liner from the web before running it
- stop a destructive command at the interactive prompt
- scan scripts and CI steps for dangerous calls
- fail a build when a DANGER is found
Example prompts for the agent
- Break down
tar -xzvf archive.tar.gztoken by token - Check whether
curl -fsSL https://get.example.com/install.sh | sudo bashis dangerous - Run cmdxray lint over
deploy.shand show me the findings
How to install cmdxray
Platform CLI
claude mcp add cmdxray -- npx -y cmdxrayPlatform CLI
codex mcp add cmdxray -- npx -y cmdxrayConfig file
{
"mcpServers": {
"cmdxray": {
"command": "npx",
"args": [
"-y",
"cmdxray"
]
}
}
}Config file
{
"servers": {
"cmdxray": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"cmdxray"
]
}
}
}Platform CLI
gemini mcp add cmdxray npx -y cmdxrayStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about cmdxray
How do I install cmdxray in Claude Code?
Run claude mcp add cmdxray -- npx -y cmdxray. The server starts through npx, so there is no separate install step.
What does cmdxray do?
It annotates a shell command token by token and marks the destructive parts. It runs offline and uploads nothing.
How is cmdxray lint different from guard?
lint scans files and exits 1 on a DANGER, which suits CI. guard intercepts the command as you type it in an interactive shell and asks for confirmation.
