Which integrations are available for this 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

How do I use Smart Shell MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by mr-wolf-gb

Overview Schema Related Servers Score Discussions

JavaScript

Local

smart-shell (MCP Server)

npm version 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: Desktop Commander MCP

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": {}
    }
  }
}

{
  "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

ParametersJSON Schema

Name	Required	Description
`projectName`	Yes	Project name used to select overrides
`commandKey`	Yes	Logical command key, e.g. install, run, test
`args`	No	Extra CLI args to append
`options`	No

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description discloses only that overrides and OS translation occur, but lacks details on safety, error cases, or side effects, which is insufficient for a command execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, but could benefit from brief usage guidelines to improve without sacrificing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 parameters, nested options, no annotations, and no output schema, the description lacks information on return value, parameter roles, and behavioral details like error handling, making it incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Description does not elaborate on any parameters; only the schema provides descriptions. With 75% schema coverage, description could have clarified missing option parameter semantics but did not. Thus no added semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes a command with project overrides and OS translation, distinguishing it from sibling tools like getProjectCommands which retrieves commands. It provides a specific verb and resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines provided; description does not advise when to use this tool versus sibling tools like translateCommand or getProjectCommands.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getProjectCommandsGet project commandsC

Return merged command mappings for a project

ParametersJSON Schema

Name	Required	Description	Default
`projectName`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description only says 'merged command mappings' without explaining what merging entails, potential errors (e.g., missing project), or output format. The behavioral disclosure is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (one sentence) and front-loaded, but it is overly terse and omits important details. It earns its place for clarity but sacrifices completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and annotations, the description should explain what 'merged command mappings' look like or any side effects. It does not, leaving the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'projectName' is a string without description in the schema (0% coverage) and the description adds no extra meaning beyond naming. No constraints or valid values are indicated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Return' and the resource 'merged command mappings' for a project, which is distinct from sibling tools (execute, remove, set, translate).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, prerequisites, or context. The description does not mention any usage constraints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

removeProjectCommandRemove a project commandC

Delete a command override for a project

ParametersJSON Schema

Name	Required	Description	Default
`projectName`	Yes
`key`	Yes

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations; description only indicates destructive action without detailing side effects, permissions, or impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise but lacks necessary detail; not overly verbose but insufficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, no annotations, and no parameter descriptions; fails to cover error conditions or return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and description provides no additional meaning for 'projectName' or 'key' parameters beyond their names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action 'Delete a command override for a project' and distinguishes from siblings like setProjectCommand and executeCommand.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no prerequisites or exclusions mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

setProjectCommandSet a project commandC

Add or update a project-specific command override

ParametersJSON Schema

Name	Required	Description	Default
`projectName`	Yes
`key`	Yes
`value`	Yes

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must convey behavioral traits. It indicates mutation ('add or update') but lacks details on side effects, overwrite behavior, permissions, or return value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no fluff. However, it is too concise, omitting critical information about parameters and usage, which reduces its overall effectiveness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 required parameters with no schema descriptions and no output schema, the description is severely lacking. It fails to explain 'command override' semantics, parameter roles, or expected behavior, leaving the agent poorly informed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, and the description does not explain the meaning or format of projectName, key, or value. The agent cannot infer what these parameters represent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Add or update a project-specific command override' clearly states the action (add/update) and the resource (project-specific command override), distinguishing it from sibling tools like getProjectCommands, removeProjectCommand, executeCommand, and translateCommand.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus siblings. Missing context about when to choose setProjectCommand over removeProjectCommand or executeCommand.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

translateCommandTranslate a raw command for this OSB

Show how a generic command would be adapted for the current OS

ParametersJSON Schema

Name	Required	Description	Default
`rawCommand`	Yes

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description implies it 'shows' adaptation, suggesting no side effects, but does not explicitly state it is read-only or non-destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no filler words. Perfectly concise for the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple schema and no output schema, the description is adequate but does not explain output format or error handling. Could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Parameter rawCommand has no description in schema, and the tool description adds no extra meaning (e.g., format examples, constraints). Coverage is 0%.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool translates/adapts a generic command for the current OS. It distinguishes from siblings like executeCommand which actually run commands.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this vs sibling tools. The agent is left to infer that this is a preview without execution, but no explicit when/when-not.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0

Disambiguation5/5

Each tool has a distinct and clearly defined purpose: executeCommand runs commands, getProjectCommands retrieves mappings, removeProjectCommand deletes overrides, setProjectCommand adds/updates overrides, and translateCommand shows OS adaptations. There is no overlap or ambiguity between these functions.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with clear, descriptive names (e.g., executeCommand, getProjectCommands, removeProjectCommand). The naming is uniform and predictable across all five tools, making them easy to distinguish and understand.

Tool Count5/5

With 5 tools, the server is well-scoped for managing command execution and project-specific overrides. Each tool serves a necessary function in the workflow, and there are no extraneous or missing tools for this domain.

Completeness5/5

The tool set provides complete coverage for the domain of command execution with project overrides and OS translation. It includes core operations: executing commands, managing overrides (get, set, remove), and translating commands, with no apparent gaps in functionality.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

SentinelX MCP
app.sentinelx
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Shell Access OS Automation
25
Kody
io.github.kentcdodds
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
Developer Tools Code Execution Command Line
2514
hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
237
mcp A
dev.aicommander
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Shell Access Command Line OS Automation
2

Related MCP Servers

Remote Command MCP Server
Shell Access Command Line OS Automation
deepsuthar496
A
license
B
quality
F
maintenance
A 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.
Updated a year ago (2025-03-25 06:42 UTC)
1
MIT
Desktop Commander MCP
Shell Access File Systems Developer Tools
MrGNSS
A
license
A
quality
D
maintenance
A server that lets Claude desktop app execute terminal commands on your computer and edit files through Model Context Protocol, featuring command execution, process management, and advanced file operations.
Updated a year ago (2025-03-23 20:47 UTC)
19
38,923
6
MIT
MCP Server
Shell Access Command Line
mokemoke0821
A
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.
Updated a year ago (2025-03-28 19:12 UTC)
25
MIT
Simple Commands MCP Server
Developer Tools Shell Access OS Automation
nstrayer
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.
Updated a year ago (2025-08-22 14:21 UTC)
11
3
MIT

Appeared in Searches

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mr-wolf-gb/smart-shell-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server