Smart Shell MCP Server
Detects Bun projects and provides intelligent command execution with automatic fallback suggestions when npm commands fail in Bun workspaces
Executes Node.js package manager commands with project-aware mappings and cross-platform shell compatibility
Executes npm commands with project-specific overrides and automatic detection of alternative package managers
Detects pnpm projects via lock files and provides intelligent command suggestions when other package managers fail
Detects Poetry Python projects and provides automatic command suggestions when pip commands fail in Poetry workspaces
Executes Python package management commands with virtual environment activation and project-aware pip/poetry selection
Detects Yarn projects via lock files and provides intelligent command suggestions when other package managers fail
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Smart Shell MCP Server install dependencies for my python-api project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
smart-shell (MCP Server)
MCP Tool Server – Cross-Platform & Project-Aware Command Runner.
This server exposes tools that execute shell commands in an OS-aware way and adapt to each project's preferred package/runtime manager (npm ↔ bun, pip ↔ poetry, etc.). Agents can read and modify per-project command mappings at runtime.
Features
OS-aware command translation (e.g.,
ls→diron Windows).Project-specific overrides stored in
src/project-commands.jsonand editable via tools.Execute mapped commands with additional args and return
{ stdout, stderr, exitCode }.Structured error objects with actionable suggestions when a command fails.
Tools:
executeCommand,getProjectCommands,setProjectCommand,removeProjectCommand,translateCommand.
Related MCP server: MCP Server
Requirements
Node.js 18+ (20+ recommended)
Install
# Dev (inside this repo)
npm install
# Production (global CLI)
npm install -g smart-shell-mcp
# or per-project without global install
npx smart-shell-mcpRun
Dev (no build):
npx tsx src/server.tsBuild + run:
npm run build
npm startThis starts an MCP server over stdio. Point your MCP-compatible client at the command above.
Configuration Files
src/command-map.json: base translation from generic commands → per-OS variants. Example:
{
"base": {
"ls": { "windows": "dir", "linux": "ls", "darwin": "ls" },
"open": { "windows": "start", "linux": "xdg-open", "darwin": "open" }
}
}src/project-commands.json: project-specific command overrides. Example:
{
"default": {
"install": "npm install",
"run": "npm start"
},
"my-bun-project": {
"install": "bun install",
"run": "bun run dev"
},
"python-api": {
"install": "pip install -r requirements.txt",
"run": "uvicorn app:app --reload"
}
}Files are looked up in the current working directory first. If not found, the copies in src/ are used and will be created automatically if missing.
Tools
executeCommand({ projectName, commandKey, args?, options? })Resolve project override → fallback to
default→ translate for OS → run.options(all optional):shell:auto | cmd | powershell | bashactivateVenv:auto | on | offvenvPath: path to a venv root if not.venv/venvcwd: working directory for the commandenv: key/value environment overrides
Returns on success:
{ "stdout": "...", "stderr": "", "exitCode": 0, "resolvedCommand": "npm install" }On failure returns structured error inside the tool result body (not thrown):
{ "errorCode": "COMMAND_FAILED", "message": "Command failed with exit code 1", "suggestion": "poetry install", "resolvedCommand": "pip install -r requirements.txt", "stdout": "...", "stderr": "...", "exitCode": 1 }
getProjectCommands({ projectName })→ merged view{ ...default, ...project }.setProjectCommand({ projectName, key, value })→ upsert and persist.removeProjectCommand({ projectName, key })→ delete and persist.translateCommand({ rawCommand })→{ os, original, translated }.
Error Handling & Suggestions
When a command exits non‑zero the server embeds a structured error with optional suggestions, e.g.:
If
npmfails and the workspace looks like a Bun project (bun.lockborpackage.json: { packageManager: "bun@..." }), suggestion:bun install(orbun run devforrun).If
pipfails andpoetry.lockor[tool.poetry]inpyproject.tomlis present, suggestion:poetry install.Also detects Yarn (
yarn.lock) and pnpm (pnpm-lock.yaml).
MCP JSON-RPC Examples
All examples assume stdio transport.
List tools:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }Call
executeCommand:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "executeCommand",
"arguments": {
"projectName": "python-api",
"commandKey": "install",
"args": ["-q"]
}
}
}Call
setProjectCommand:
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "setProjectCommand",
"arguments": {
"projectName": "my-bun-project",
"key": "lint",
"value": "bun run lint"
}
}
}IDE Integration (Production)
After installing globally (npm i -g smart-shell-mcp), configure your IDE to run the smart-shell executable over stdio.
Cursor, Kiro, Windsurf (example)
{
"mcpServers": {
"smart-shell": {
"command": "npx",
"args": [
"-y",
"smart-shell-mcp"
],
"env": {}
}
}
}Or
{
"mcpServers": {
"smart-shell": {
"command": "smart-shell",
"args": [],
"env": {}
}
}
}Claude Desktop (reference)
{
"mcpServers": {
"smart-shell": { "command": "smart-shell" }
}
}Notes
If you prefer not to install globally, replace
smart-shellwithnpx smart-shell-mcpin the examples above.Windows users can switch to PowerShell execution with the tool options (see below) if needed.
Project Scripts
npm run dev– start in dev (tsx)npm run build– build TypeScript todist/npm start– run compiled servernpm run typecheck– TypeScript type checking
Made with ❤️ by Mr-Wolf-GB for the MCP community
Available Tools
5 toolsexecuteCommandExecute a project-aware commandC
Executes a command after applying project overrides and OS translation
Inputs: projectName (required), commandKey (required), args, options.
getProjectCommandsGet project commandsC
Return merged command mappings for a project
Inputs: projectName (required).
removeProjectCommandRemove a project commandC
Delete a command override for a project
Inputs: projectName (required), key (required).
setProjectCommandSet a project commandC
Add or update a project-specific command override
Inputs: projectName (required), key (required), value (required).
translateCommandTranslate a raw command for this OSB
Show how a generic command would be adapted for the current OS
Inputs: rawCommand (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clear, distinct role: execution, preview/translation, and project command override CRUD. There is no meaningful overlap between executing a command and merely showing its translated form.
All tool names follow a consistent camelCase verb-first pattern: execute, translate, get, set, remove. The naming style is uniform and predictable.
Five tools is well-scoped for a smart shell server covering execution, translation, and project-specific command overrides. Each tool earns its place with no redundancy.
The core workflow is covered well: execute, preview, and full CRUD for project command overrides. A minor gap is the lack of a way to enumerate all projects with overrides, but this is a workaround limitation rather than a dead end.
Maintenance
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables remote execution of shell commands across different operating systems, automatically handling platform-specific differences between Windows and Unix-like systems.1MIT
- FlicenseNot gradedqualityDmaintenanceA cross-platform shell command execution server that supports Windows, macOS, and Linux environments with PowerShell, CMD, GitBash, and Bash shells, optimized for Japanese language environments.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to execute predefined developer commands and manage long-running processes through a JSON configuration file. Supports both one-shot commands and daemon processes with automatic process lifecycle management.6 npm3MIT
- FlicenseBqualityDmaintenanceEnables safe execution of system shell commands with real-time streaming output and rich metadata capture. Provides configurable command execution with timeout controls, environment management, and extensible plugin architecture for monitoring command lifecycles.4-