MCPShell MCP server

The MCPShell is a tool that allows Large Language Models (LLMs) to safely execute command-line tools through the Model Context Protocol (MCP). It creates a secure bridge between LLMs and operating system commands, enabling AI assistants to interact with your system through controlled interfaces.

Installation

Prerequisites

You need to have Go installed on your system to run MCPShell.

Setting Up MCPShell

1. Create a configuration file defining your tools. For example, create /my/example.yaml:

mcp:
  description: |
    Tool for analyzing disk usage to help identify what's consuming space.
  run:
    shell: bash
  tools:
    - name: "disk_usage"
      description: "Check disk usage for a directory"
      params:
        directory:
          type: string
          description: "Directory to analyze"
          required: true
        max_depth:
          type: number
          description: "Maximum depth to analyze (1-3)"
          default: 2
      constraints:
        - "directory.startsWith('/')"  # Must be absolute path
        - "!directory.contains('..')"  # Prevent directory traversal
        - "max_depth >= 1 && max_depth <= 3"  # Limit recursion depth
        - "directory.matches('^[\\w\\s./\\-_]+$')"  # Only allow safe path characters
      run:
        command: |
          du -h --max-depth={{ .max_depth }} {{ .directory }} | sort -hr | head -20
      output:
        prefix: |
          Disk Usage Analysis (Top 20 largest directories):

2. Configure your MCP client to use MCPShell.

For Cursor

Create a .cursor/mcp.json file:

{
    "mcpServers": {
        "mcp-cli-examples": {
            "command": "go",
            "args": [
               "run", "github.com/inercia/[email protected]",
               "mcp", "--config", "/my/example.yaml",
               "--logfile", "/some/path/mcpshell/example.log"
            ]
        }
    }
}

For Visual Studio Code

Configure MCPShell as an MCP server in your VS Code settings.

Usage

Basic Usage

1. After configuring MCPShell and your MCP client, refresh your client if necessary
2. Start interacting with your LLM, asking it to perform tasks using the tools you've defined
3. For example, ask: "I'm running out of space in my hard disk. Could you help me finding the problem?"

Creating Tool Configurations

MCPShell tools are defined in YAML configuration files with the following key components:

• Tool definitions: Name, description, and parameters
• Constraints: Security rules for parameter validation
• Command templates: How the tool executes shell commands
• Output formatting: How results are displayed

Example Tool Configuration

Here's a breakdown of the disk usage tool:

- name: "disk_usage"                   # Tool name
  description: "Check disk usage..."   # Tool description
  params:                              # Parameters the tool accepts
    directory:
      type: string
      description: "Directory to analyze"
      required: true
    max_depth:
      type: number
      description: "Maximum depth to analyze (1-3)"
      default: 2
  constraints:                         # Security constraints
    - "directory.startsWith('/')"
    - "!directory.contains('..')"
    - "max_depth >= 1 && max_depth <= 3"
    - "directory.matches('^[\\w\\s./\\-_]+$')"
  run:                                 # Command template
    command: |
      du -h --max-depth={{ .max_depth }} {{ .directory }} | sort -hr | head -20
  output:                              # Output formatting
    prefix: |
      Disk Usage Analysis (Top 20 largest directories):

Agent Mode

MCPShell can also run in agent mode, connecting directly to LLM APIs without requiring a separate MCP client.

Running in Agent Mode

To use agent mode:

go run github.com/inercia/MCPShell agent --config your-config.yaml

This mode enables:

• Direct connection to OpenAI-compatible APIs (including local LLMs like Ollama)
• Interactive or one-shot conversations
• Custom system and user prompts defined in your configuration

Security Best Practices

When using MCPShell, follow these important security guidelines:

• Limit tools to read-only actions whenever possible
• Use constraints to validate parameters before execution
• Consider using sandboxed environments for command execution
• Review command templates for potential injection vulnerabilities
• Only expose tools that are safe for external use

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp-cli-examples" '{"command":"go","args":["run","github.com/inercia/[email protected]","mcp","--config","/my/example.yaml","--logfile","/some/path/mcpshell/example.log"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcp-cli-examples": {
            "command": "go",
            "args": [
                "run",
                "github.com/inercia/[email protected]",
                "mcp",
                "--config",
                "/my/example.yaml",
                "--logfile",
                "/some/path/mcpshell/example.log"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp-cli-examples": {
            "command": "go",
            "args": [
                "run",
                "github.com/inercia/[email protected]",
                "mcp",
                "--config",
                "/my/example.yaml",
                "--logfile",
                "/some/path/mcpshell/example.log"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect