/ 
MCP-Run-0.100
/ mcp-run-bash

NAME

mcp-run-bash - MCP server that executes shell commands via bash over stdio

VERSION

version 0.100

SYNOPSIS

# Start with defaults (all commands allowed, 30s timeout):
$ mcp-run-bash

# Restrict to a set of commands:
$ MCP_RUN_ALLOWED_COMMANDS=ls,cat,grep mcp-run-bash

# Pin working directory and enable compressed output:
$ MCP_RUN_WORKING_DIRECTORY=/var/data MCP_RUN_COMPRESS=1 mcp-run-bash

DESCRIPTION

mcp-run-bash starts an MCP (Model Context Protocol) server on stdio that exposes a single run tool. The tool executes a command string via bash -c, capturing stdout, stderr and exit code, and returns them to the MCP client.

This is the entry point for wiring MCP::Run::Bash into Claude Desktop, Claude Code or any other MCP-compatible client.

NAME

mcp-run-bash - MCP server that executes shell commands via bash over stdio

CONFIGURATION

The server is configured entirely through environment variables so it can be declared directly in an MCP client configuration file.

Environment Variables

MCP_RUN_ALLOWED_COMMANDS

Comma-separated list of command names that may be executed (matched against the first word of the command). When unset, all commands are allowed.

MCP_RUN_WORKING_DIRECTORY

Default working directory for command execution. Overridable per-call via the tool's working_directory argument.

MCP_RUN_TIMEOUT

Default timeout in seconds. Defaults to 30. Overridable per-call.

MCP_RUN_COMPRESS

Toggle output compression (noise filtering, line truncation) for LLM efficiency. Enabled by default in this script — set to 0, false, no or off to disable. Overridable per-call via the tool's compress argument.

MCP_RUN_TOOL_NAME

Name under which the tool is registered. Defaults to run.

CLAUDE DESKTOP

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "run": {
      "command": "mcp-run-bash",
      "env": {
        "MCP_RUN_ALLOWED_COMMANDS": "ls,cat,grep,find",
        "MCP_RUN_WORKING_DIRECTORY": "/home/me/project"
      }
    }
  }
}

CLAUDE CODE

Add to your project's .mcp.json:

{
  "mcpServers": {
    "run": {
      "command": "mcp-run-bash",
      "env": {
        "MCP_RUN_COMPRESS": "1"
      }
    }
  }
}

SEE ALSO

MCP::Run::Bash — the module that powers this script

MCP::Run — base class defining the run MCP tool

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-mcp-run/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.