script-runner
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
script-runner-mcp
An MCP server that lets an AI agent run the local scripts you declared, and nothing else. Arguments are checked before anything starts, and no shell is involved.
Why this exists
My agents work inside a Linux sandbox. Some jobs need the host machine instead. One example is rendering branded images with Puppeteer: the sandbox has no Chrome, no root and no way to download one. The render scripts worked fine on the host, but the agent could not reach them.
So the agent improvised. It drew title images with Pillow, and they came out off-brand. A rule in its instructions saying "never render with Pillow" didn't stop it, because from the agent's point of view a workaround still beat failing the task.
The fix was to give it a proper path: a small MCP server on the host that exposes the render scripts as tools. The first version hard-coded two script paths. This is the general version. You declare each script, its arguments and the parameters the agent may fill in, and the agent gets exactly those tools. There is no generic "run command" tool.
Related MCP server: MCP Process Server
How it works
Declared tools only. A JSON config lists each tool: the program (
nodeby default), an optional script, an argument template and typed parameters.Checked parameters.
pathparameters must resolve, after following symlinks, inside one of theallowed_rootsand can be limited to certain extensions.integerparameters have ranges,enumparameters have fixed values, andstringparameters have a length limit, an optional pattern and must not start with-, so they cannot smuggle in options. Unknown arguments are rejected.No shell. The process starts via
execFilewithshell: false, so&&,$(...)or;in an argument stay plain text.Bounded runs. Each tool has a timeout. Output is capped. A failure comes back as an MCP tool error with exit code and stderr.
Zero runtime dependencies. It speaks JSON-RPC over stdio directly in about 500 lines of plain Node.js, so there is little to audit.
Installation
You need Node.js 22 or newer.
npx -y github:michael-schilde/script-runner-mcp --config path/to/config.json --check--check validates the config and prints the tools it would expose. Then register the server with your MCP client, for example in Claude Desktop's claude_desktop_config.json:
{
"mcpServers": {
"script-runner": {
"command": "npx",
"args": ["-y", "github:michael-schilde/script-runner-mcp", "--config", "/absolute/path/to/config.json"]
}
}
}You can also clone the repository and point the client at node /path/to/script-runner-mcp/src/cli.js. Instead of --config you can set the SCRIPT_RUNNER_CONFIG environment variable.
Example: a Puppeteer render script
{
"allowed_roots": ["./images"],
"tools": [
{
"name": "render_title_image",
"description": "Renders a 1200x630 title image from a JSON spec and prints the PNG path.",
"script": "./render/render.js",
"args": ["{spec}"],
"params": {
"spec": { "type": "path", "required": true, "extensions": [".json"], "description": "Image spec" }
},
"timeout_ms": 120000
}
]
}The agent sees one tool, render_title_image, with one argument. A spec outside ./images, a .js file or an extra argument is rejected before Node starts.
A runnable demo lives in examples/: count_words counts the words of a text file inside examples/content.
Configuration
Relative paths are resolved against the folder that contains the config file.
Key | Meaning |
| Folders that |
| Tool name ( |
| Shown to the agent |
|
|
| Optional script passed as the first argument |
| Argument templates; |
| Parameters the agent may pass (see below) |
| Working directory (default: the config folder) |
| Timeout, default 60000, max 600000 |
| Extra environment variables for the process |
Parameter rule | Meaning |
|
|
| Whether the agent must pass it, and the value used when it does not |
| Shown to the agent |
|
|
|
|
|
|
|
|
|
|
Limits
The script is trusted. The server controls what the agent may pass in, not what your script does with it. A script that runs
evalon its input is still dangerous.Inherited environment. Child processes get the server's environment plus
env, so tools like Puppeteer find their caches. Do not put secrets in the server's environment if your scripts should not see them.No
.cmdor.baton Windows. Without a shell, Node cannot start batch files. Pointcommandat a real executable (node,python,.exe).Tools only. The server implements
initialize,ping,tools/listandtools/call. It has no resources, prompts, progress notifications or cancellation, and a long run just waits for its timeout.Platforms. I use it on Windows. CI runs the tests on Linux and Windows.
Development
npm install
npm test
npm run lintAbout
I built this with Claude Code. It grew out of the render bridge in my own agent setup. Issues and pull requests are welcome.
License
MIT © Michael Schilde
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides safe shell command execution capabilities for AI agents and tools like VS Code Copilot through a whitelist-based filtering system.-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to launch and manage system processes with strict security controls through executable allowlists, resource monitoring, and output capture capabilities.85 npm1MIT
- FlicenseAqualityDmaintenanceEnables AI to execute registered system commands across platforms using a stable program + args interface, without requiring shell-specific syntax or tool discovery.21-
- AlicenseNot gradedqualityCmaintenanceEnables controlled delegation of tasks to local coding-agent CLIs and the Manus API, with strict sandboxing, approval tracking, and remote-egress safeguards.MIT