Smart-Shell

You can run project-aware shell commands across different runtimes and package managers with smart-shell MCP Server. It translates generic commands to OS-specific variants, applies per-project overrides, and returns structured results that help you automate and troubleshoot command execution inside your development environment.

How to use

Use smart-shell MCP Server with an MCP client to execute mapped commands for a given project. The server consults per-project overrides, applies OS-specific translations, and runs the resulting command with any extra arguments you provide. You receive a structured result containing stdout, stderr, and exit code, as well as a translated command that was actually executed. If a command fails, you get a helpful error object with actionable suggestions to fix common issues (for example, suggesting bun or poetry equivalents when a Bun or Poetry project is detected). You can also query, set, and remove per-project command mappings during runtime.

Key workflow patterns include: selecting a project override, translating a generic command into the right variant for your OS, and executing the command with optional environment overrides, working directory, and virtual environment controls. You can adjust how commands are run, including shell type (auto, cmd, powershell, bash) and whether to activate a virtual environment.

How to install

# Prerequisites
node -v  # ensure Node.js 18+ is installed
npm -v   # npm is available with Node.js

# Dev installation inside the project context
npm install

# Production / global CLI usage
# Option A: install globally for easy access
npm install -g smart-shell-mcp

# Option B: run locally per project without a global install
npx smart-shell-mcp

If you prefer to run the server directly in development mode, you can start it with the development command for rapid iteration. For a production-ready start, install dependencies, build the project, and run the compiled server.

Configuration and usage notes

Configuration lives in per-project command maps. The base translations determine OS-specific command variants, and project-specific overrides can be stored and edited to tailor behavior for each project. Lookups follow this order: project override → default → OS translation.

Common configuration files include a base translation map and per-project overrides. You can adjust mappings such as using bun instead of npm for a Bun-based project or using poetry instead of pip for a Poetry-managed Python project. The server also exposes a translateCommand function that reveals the OS, the original command, and the translated command that will run.

Error handling and helpful suggestions

When a command exits with a non-zero status, the server returns a structured error object that can include a suggested fix. For example, if a Bun project is detected and npm fails, you may be advised to run bun install or bun run dev. If a Python project uses Poetry and a Poetry file is present, you may receive a suggestion to run poetry install. The server also detects yarn and pnpm when their lock files are present.

Available tools

executeCommand

Runs a mapped command for a given project, applying per-project overrides and OS translations. Returns stdout, stderr, exitCode, and the resolved command.

getProjectCommands

Returns the merged view of default and project-specific command mappings for a given project.

setProjectCommand

Adds or updates a per-project command override and persists it.

removeProjectCommand

Removes a per-project command override and persists the change.

translateCommand

Translates a raw command into an OS-appropriate variant, showing the OS, original, and translated forms.