Skip to main content
Glama
Smart Shell MCP Server

Smart Shell MCP Server

by mr-wolf-gb

smart-shell (MCP Server)

npm version CI Node.js Version License: GPL-3.0 MCP Compatible

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 → dir on Windows).

  • Project-specific overrides stored in src/project-commands.json and 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-mcp

Run

  • Dev (no build):

npx tsx src/server.ts
  • Build + run:

npm run build
npm start

This 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 | bash

      • activateVenv: auto | on | off

      • venvPath: path to a venv root if not .venv/venv

      • cwd: working directory for the command

      • env: 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 npm fails and the workspace looks like a Bun project (bun.lockb or package.json: { packageManager: "bun@..." }), suggestion: bun install (or bun run dev for run).

  • If pip fails and poetry.lock or [tool.poetry] in pyproject.toml is 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-shell with npx smart-shell-mcp in 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 to dist/

  • npm start – run compiled server

  • npm run typecheck – TypeScript type checking

Made with ❤️ by Mr-Wolf-GB for the MCP community

Available Tools

5 tools
executeCommandExecute 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

    B3.3/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tool names follow a consistent camelCase verb-first pattern: execute, translate, get, set, remove. The naming style is uniform and predictable.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      3
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      Enables 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
      -