Mkusaka MCP Shell Server

🚀 MCP Shell Server

A server that uses the Model Context Protocol (MCP) to execute shell commands. It acts as a bridge, allowing AI agents to securely execute shell commands.

🚀 Quick Start

The MCP Shell Server is a useful tool for AI agents to execute shell commands. Here are the basic steps to get started:

1. Install the server.
2. Configure MCP settings.
3. Start using the server to execute shell commands.

✨ Features

• Execute shell commands (supports single-line and multi-line commands).
• Support multiple shells (bash, zsh, fish, powershell, cmd, etc.).
• Detailed error handling and logging.
• Compatible with MCP Inspector.

📦 Installation

Install using npm (as a user)

# Using npm
npm install -g @mkusaka/mcp-shell-server

# Using yarn
yarn global add @mkusaka/mcp-shell-server

# Using pnpm
pnpm add -g @mkusaka/mcp-shell-server

Install from source code (for development)

# Clone the repository
git clone https://github.com/mkusaka/mcp-shell-server.git
cd mcp-shell-server

# Install dependencies
pnpm install

# Build the project
pnpm build

📚 Documentation

MCP Configuration

Cursor Configuration

Add the following content to your Cursor configuration file (~/.cursor/config.json):

{
  "mcpServers": {
    "shell": {
      "command": "npx",
      "args": ["-y", "@mkusaka/mcp-shell-server"]
    }
  }
}

Rule Configuration

Add the following content to your Cursor rule file:

You have tools available to solve tasks. Please follow the following rules regarding tool invocation:
1. **Always** specify parameters exactly according to the tool invocation pattern.
2. Tools that are no longer provided may be referenced in the conversation. **Never invoke tools that are not explicitly provided**.
3. **Never mention the tool name when conversing with the user**. For example, don't say "I need to use the shell_exec tool to execute your command", but rather say "I'll execute your command" directly.
4. Only invoke tools when necessary. If the user's task is general or you already know the answer, respond directly without invoking a tool.
5. Before each tool invocation, explain to the user why the tool needs to be invoked.

Usage

Direct Execution

node dist/index.js
# Or run as an executable file
./dist/index.js

Development Mode

pnpm dev

Test with MCP Inspector

pnpm inspect

Command-line Arguments

-s, --shell <shell>  Specify the path of the shell to use
-h, --help           Display help information
-V, --version        Display version information

Tool References

shell_exec

Execute a command in the specified shell.

Parameters:

• command (string, required): The shell command to execute

Resource References

The server provides the following system information as resources:

hostname

Returns the system's hostname.

URI: hostname://

platform

Returns the operating system platform.

URI: platform://

shell

Returns the path of the shell used by the server.

URI: shell://

username

Returns the current username.

URI: username://

system-info

Returns comprehensive system information (in JSON format) including the following:

• Hostname
• Platform
• Shell
• Username
• Number of CPU cores
• Total memory
• Free memory
• System uptime

💻 Usage Examples

Basic Usage

{
  "name": "shell_exec",
  "parameters": {
    "command": "echo Hello, World!"
  }
}

Advanced Usage

{
  "name": "shell_exec",
  // Here you can add more complex commands or scenarios according to your needs
}