CLI MCP Server

Um servidor MCP seguro para executar operações controladas de linha de comando com recursos abrangentes de segurança.

Documentação

CLI MCP Server

Uma implementação segura de servidor Model Context Protocol (MCP) para executar operações controladas de linha de comando com recursos abrangentes de segurança.

Sumário

Visão Geral
Recursos
Configuração
Ferramentas Disponíveis
- run_command
- show_security_rules
Uso com o Claude Desktop
- Configuração de Servidores em Desenvolvimento/Não Publicados
- Configuração de Servidores Publicados
Recursos de Segurança
Tratamento de Erros
Desenvolvimento
Licença

Visão Geral

Este servidor MCP permite execução segura de linha de comando com medidas robustas de segurança, incluindo lista de permissões de comandos, validação de caminhos e controles de execução. Perfeito para fornecer acesso CLI controlado a aplicações LLM mantendo a segurança.

Recursos

🔒 Execução segura de comandos com validação rigorosa
⚙️ Lista configurável de comandos e flags permitidos com opção 'all'
🛡️ Prevenção e validação contra traversal de caminhos
🚫 Proteção contra injeção de operadores de shell
⏱️ Timeouts de execução e limites de tamanho
📝 Relatórios de erro detalhados
🔄 Suporte a operações assíncronas
🎯 Restrição e validação do diretório de trabalho

Configuração

Configure o servidor usando variáveis de ambiente:

Variável	Descrição	Padrão
`ALLOWED_DIR`	Diretório base para execução de comandos (Obrigatório)	Nenhum (Obrigatório)
`ALLOWED_COMMANDS`	Lista separada por vírgulas de comandos permitidos ou 'all'	`ls,cat,pwd`
`ALLOWED_FLAGS`	Lista separada por vírgulas de flags permitidos ou 'all'	`-l,-a,--help`
`MAX_COMMAND_LENGTH`	Tamanho máximo da string de comando	`1024`
`COMMAND_TIMEOUT`	Timeout de execução de comandos (segundos)	`30`
`ALLOW_SHELL_OPERATORS`	Permitir operadores de shell (&&, \|\|, \|, >, etc.)	`false`

Observação: Definir ALLOWED_COMMANDS ou ALLOWED_FLAGS como 'all' permitirá qualquer comando ou flag, respectivamente.

Instalação

Para instalar o CLI MCP Server para o Claude Desktop automaticamente via Smithery:

npx @smithery/cli install cli-mcp-server --client claude

Ferramentas Disponíveis

run_command

Executa comandos CLI permitidos dentro de diretórios autorizados.

Esquema de Entrada:

{
  "command": {
    "type": "string",
    "description": "Single command to execute (e.g., 'ls -l' or 'cat file.txt')"
  }
}

Observações de Segurança:

Operadores de shell (&&, |, >, >>) não são suportados por padrão, mas podem ser habilitados com ALLOW_SHELL_OPERATORS=true
Os comandos devem estar na lista de permissões, a menos que ALLOWED_COMMANDS='all'
As flags devem estar na lista de permissões, a menos que ALLOWED_FLAGS='all'
Todos os caminhos são validados para estar dentro de ALLOWED_DIR

show_security_rules

Exibe a configuração de segurança atual e as restrições, incluindo:

Diretório de trabalho
Comandos permitidos
Flags permitidos
Limites de segurança (tamanho máximo de comando e timeout)

Uso com o Claude Desktop

Adicione ao seu ~/Library/Application\ Support/Claude/claude_desktop_config.json:

Configuração de Servidores em Desenvolvimento/Não Publicados

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/the/repo>/cli-mcp-server",
        "run",
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/dir>",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
        "ALLOWED_FLAGS": "-l,-a,--help,--version",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

Configuração de Servidores Publicados

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uvx",
      "args": [
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/dir>",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
        "ALLOWED_FLAGS": "-l,-a,--help,--version",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

Caso não esteja funcionando ou não apareça na interface, limpe seu cache via uv clean.

Recursos de Segurança

✅ Aplicação da lista de permissões de comandos com opção 'all'
✅ Validação de flags com opção 'all'
✅ Prevenção e normalização contra traversal de caminhos
✅ Bloqueio de operadores de shell (com suporte opcional via ALLOW_SHELL_OPERATORS=true)
✅ Limites de tamanho de comando
✅ Timeouts de execução
✅ Restrições de diretório de trabalho
✅ Resolução e validação de symlinks

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para:

Violações de segurança (CommandSecurityError)
Timeouts de comando (CommandTimeoutError)
Formatos de comando inválidos
Violações de segurança de caminho
Falhas de execução (CommandExecutionError)
Erros gerais de comando (CommandError)

Desenvolvimento

Pré-requisitos

Python 3.10+
Biblioteca de protocolo MCP

Compilação e Publicação

Para preparar o pacote para distribuição:

Sincronize as dependências e atualize o lockfile:
```
uv sync
```
Compile as distribuições do pacote:
```
uv build
```
Isso criará distribuições de origem e wheel no diretório dist/.

Publique no PyPI:

uv publish --token {{YOUR_PYPI_API_TOKEN}}

Depuração

Como os servidores MCP são executados via stdio, a depuração pode ser desafiadora. Para a melhor experiência de depuração, recomendamos fortemente usar o MCP Inspector.

Você pode iniciar o MCP Inspector via npm com este comando:

npx @modelcontextprotocol/inspector uv --directory {{your source code local directory}}/cli-mcp-server run cli-mcp-server

Ao iniciar, o Inspector exibirá uma URL que você pode acessar no seu navegador para começar a depurar.

Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

Para mais informações ou suporte, abra uma issue no repositório do projeto.