convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
g0t4

MCP Server Commands

g0t4/mcp-server-commands

Execute comandos do sistema através de Claude e outros modelos LLM

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que expõe a ferramenta `runProcess` para executar comandos e processos no sistema host. Permite que modelos de IA rodem comandos via shell ou invocação direta, capturando saída padrão e erro.

Instalação

$npx convez-ai g0t4/mcp-server-commands

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
237
Forks
34
Acompanhando
4
Saúde
42%
Último commit
há 3 semanas
Versão
v0.8.2
Issues abertas
8
Contribuidores
3

Casos de uso

  • Automação de tarefas administrativas via conversa com IA
  • Execução de scripts e processamento de dados em tempo real
  • Integração de fluxos de trabalho que requerem interação com o sistema operacional

Veredito

Ferramenta poderosa para automação de linha de comando via MCP, com suporte robusto a shell e invocação direta. Requer cuidado quanto à segurança — use aprovação por comando em ambientes de desktop para evitar execuções indesejadas.

README

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

runProcess tool

The runProcess tool runs processes on the host machine. There are two mutually exclusive ways to invoke it:

  1. command_line (string) — Executed via the system's default shell (just like typing into bash/fish/pwsh/etc). Shell features like pipes, redirects, and variable expansion all work.
  2. argv (string array) — Direct executable invocation. argv[0] is the executable, the rest are arguments. No shell interpretation.

You cannot pass both. The tool infers whether to use a shell from which parameter you provide.

If you want your model to use specific shell(s) on a system, I would list them in your system prompt. Or, maybe in your tool instructions, though models tend to pay better attention to examples in a system prompt.

Let me know if you encounter problems!

Tools

Tools are for LLMs to request. Claude Sonnet 3.5 intelligently uses run_process. And, initial testing shows promising results with Groq Desktop with MCP and llama4 models.

Currently, just one command to rule them all!

  • run_process - run a command, i.e. hostname or ls -al or echo "hello world" etc
    • Returns STDOUT and STDERR as text
    • Optional stdin parameter means your LLM can
      • pass scripts over STDIN to commands like fish, bash, zsh, python
      • create files with cat >> foo/bar.txt from the text in stdin

[!WARNING] Be careful what you ask this server to run! In Claude Desktop app, use Approve Once (not Allow for This Chat) so you can review each command, use Deny if you don't trust the command. Permissions are dictated by the user that runs the server. DO NOT run with sudo.

Video walkthrough

Prompts

Prompts are for users to include in chat history, i.e. via Zed's slash commands (in its AI Chat panel)

  • run_process - generate a prompt message with the command output
  • FYI this was mostly a learning exercise... I see this as a user requested tool call. That's a fancy way to say, it's a template for running a command and passing the outputs to the model!

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Installation

To use with Claude Desktop, add the server config:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Groq Desktop (beta, macOS) uses ~/Library/Application Support/groq-desktop-app/settings.json

Use the published npm package

Published to npm as mcp-server-commands using this workflow

{
  "mcpServers": {
    "mcp-server-commands": {
      "command": "npx",
      "args": ["mcp-server-commands"]
    }
  }
}

Use a local build (repo checkout)

Make sure to run npm run build

{
  "mcpServers": {
    "mcp-server-commands": {
      // works b/c of shebang in index.js
      "command": "/path/to/mcp-server-commands/build/index.js"
    }
  }
}

Local Models

  • Most models are trained such that they don't think they can run commands for you.
    • Sometimes, they use tools w/o hesitation... other times, I have to coax them.
    • Use a system prompt or prompt template to instruct that they should follow user requests. Including to use run_processs without double checking.
  • Ollama is a great way to run a model locally (w/ Open-WebUI)
# NOTE: make sure to review variants and sizes, so the model fits in your VRAM to perform well!

# Probably the best so far is [OpenHands LM](https://www.all-hands.dev/blog/introducing-openhands-lm-32b----a-strong-open-coding-agent-model)
ollama pull https://huggingface.co/lmstudio-community/openhands-lm-32b-v0.1-GGUF

# https://ollama.com/library/devstral
ollama pull devstral

# Qwen2.5-Coder has tool use but you have to coax it
ollama pull qwen2.5-coder

HTTP / OpenAPI

The server is implemented with the STDIO transport. For HTTP, use mcpo for an OpenAPI compatible web server interface. This works with Open-WebUI

uvx mcpo --port 3010 --api-key "supersecret" -- npx mcp-server-commands

# uvx runs mcpo => mcpo run npx => npx runs mcp-server-commands
# then, mcpo bridges STDIO <=> HTTP

[!WARNING] I briefly used mcpo with open-webui, make sure to vet it for security concerns.

Logging

Claude Desktop app writes logs to ~/Library/Logs/Claude/mcp-server-mcp-server-commands.log

By default, only important messages are logged (i.e. errors). If you want to see more messages, add --verbose to the args when configuring the server.

By the way, logs are written to STDERR because that is what Claude Desktop routes to the log files. In the future, I expect well formatted log messages to be written over the STDIO transport to the MCP client (note: not Claude Desktop app).

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Ver o original no GitHub

Bom para

Relacionados