MCP Shell Server

🚀 MCP Shell Server

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

🚀 Quick Start

The MCP Shell Server is a crucial tool that enables AI agents to execute shell commands securely using the Model Context Protocol (MCP). It supports multiple shells and provides detailed error handling and logging.

✨ Features

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

📦 Installation

Install from npm (for users)

# 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"]
    }
  }
}

Cline Integration

Add the following content to ~/.config/cursor/cursor.json:

{
  "shell": {
    "serverUrl": "http://localhost:13000"
  }
}

Usage

Basic Command Execution

npx mcp-shell-server

System Information Query

Access the following interfaces to get system information:

• http://localhost:13000/system-info
• http://localhost:13000/shell (returns the path of the currently used shell)

Configuration Options

npx mcp-shell-server --port=13000 --config=config.json

Parameter descriptions:

• --port: Specify the port the server listens on, default is 13000.
• --config: Specify the path to the configuration file.

💻 Usage Examples

Basic Usage

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

Advanced Usage

{
  "name": "shell_exec",
  "parameters": {
    "command": "cat << EOF | grep 'example'\nThis is an example text.\nAnother line without the keyword.\nEOF"
  }
}

🔧 Technical Details

Project Structure

src/
├── index.ts                # Main entry file
└── shell-server/
    ├── index.ts            # Shell server implementation
    └── lib/
        └── logger.ts       # Log configuration

Logging

Logs are output to the mcp-shell.log file.

📄 License

MIT