convez.ai
MCP ServerAutomaçãoIntermediário
inercia

MCPShell - Executor de Scripts Shell via MCP

inercia/mcp-cli-adapter

Execute scripts e comandos shell como ferramentas MCP com segurança

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que permite LLMs executar comandos shell de forma segura através de definições YAML. Fornece validação de parâmetros com expressões CEL, suporte a ambientes sandboxeados e integração direta com clientes MCP como Cursor e VSCode.

Instalação

$npx convez-ai inercia/mcp-cli-adapter

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
72
Forks
16
Acompanhando
2
Saúde
57%
Último commit
há 3 meses
Versão
v0.2.0
Issues abertas
7
Contribuidores
6

Casos de uso

  • Integrar ferramentas CLI (kubectl, aws-cli, etc) ao Claude/Cursor
  • Criar assistentes que analisem o sistema de arquivos ou recursos
  • Prototipagem rápida de ferramentas customizadas para LLMs
  • Automatizar tarefas operacionais com validação segura de parâmetros

Veredito

Solução prática para expor comandos shell ao Claude via MCP com camada de segurança (CEL constraints). Ideal para quem quer estender capacidades de LLMs com ferramentas CLI existentes, mas requer entendimento de YAML e expressões de validação.

README

A tradução para o português deste README ainda está na fila.

MCPShell

The MCPShell is a tool that allows LLMs to safely execute command-line tools through the Model Context Protocol (MCP). It provides a secure bridge between LLMs and operating system commands.

Features

  • Flexible command execution: Run any shell commands as MCP tools, with parameter substitution through templates.
  • Configuration-based tool definitions: Define tools in YAML with parameters, constraints, and output formatting.
  • Security through constraints: Validate tool parameters using CEL expressions before execution, as well as optional sanboxed environments for running commands.
  • Quick proptotyping of MCP tools: just add some shell code and use it as a MCP tool in your LLM.
  • Simple integration: Works with any LLM client supporting the MCP protocol (ie, Cursor, VSCode, Witsy...)

Quick Start

Imagine you want Cursor (or some other MCP client) help you with your space problems in your hard disk.

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

    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, prevent command injection
          run:
            command: |
              du -h --max-depth={{ .max_depth }} {{ .directory }} | sort -hr | head -20
          output:
            prefix: |
              Disk Usage Analysis (Top 20 largest directories):
    

    Take a look at the examples directory for more sophisticated and useful examples. Maybe you prefer to let the LLM know about your Kubernetes cluster with kubectl? Or let it run some AWS CLI commands?

  2. Configure the MCP server in Cursor (or in any other LLM client with support for MCP)

    For example, for Cursor, create .cursor/mcp.json:

    {
        // you need the "go" command available
        "mcpServers": {
            "mcp-cli-examples": {
                "command": "go",
                "args": [
                   "run", "github.com/inercia/MCPShell@v0.1.8",
                   "mcp", "--tools", "/my/example.yaml",
                   "--logfile", "/some/path/mcpshell/example.log"
                ]
            }
        }
    }
    

    You can also use relative paths and omit the .yaml extension:

    {
        "mcpServers": {
            "mcp-cli-examples": {
                "command": "go",
                "args": [
                   "run", "github.com/inercia/MCPShell@v0.1.8",
                   "mcp", "--tools", "example",
                   "--logfile", "/some/path/mcpshell/example.log"
                ]
            }
        }
    }
    

    This will look for example.yaml in the tools directory (~/.mcpshell/tools/ by default).

    See more details on how to configure Cursor or Visual Studio Code. Other LLMs with support for MCPs should be configured in a similar way.

  3. Make sure your MCP client is refreshed (Cursor should recognize it automatically the firt time, but any change in the config file will require a refresh).

  4. Ask your LLM some questions it should be able to answer with the new tool. For example: "I'm running out of space in my hard disk. Could you help me finding the problem?".

Usage and Configuration

Take a look at all the command in this document.

Configuration files use a YAML format defined here. See the this directory for some examples.

For deploying MCPShell in containers and Kubernetes, see the Container Deployment Guide.

Agent Mode

For AI agent functionality that connects LLMs directly to tools, see the Don project. Don provides:

  • Direct LLM connectivity without requiring a separate MCP client
  • RAG (Retrieval-Augmented Generation) support
  • Multi-agent architecture
  • Uses MCPShell's tool configuration format

Security Considerations

So you will probably thing "this AI has helped me finding all those big files. What if I create another tool for removing files?". Don't do that!.

  • Limit the scope of these tools to read-only actions, do not give the LLM the power to change things.
  • Use constraints to limit command execution to safe parameters
  • Consider using a sanboxed environment for running commands.
  • Review all command templates for potential injection vulnerabilities
  • Only expose tools that are safe for external use
  • All of the above!

Please read the Security Considerations document before using this software.

Contributing

Contributions are welcome! Take a look at the development guide. Please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Ver o original no GitHub

Bom para

Relacionados