commands

What is mcp-server-commands?

mcp-server-commands is a Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to execute commands and scripts on the host system, similar to a terminal. It provides a run_command tool that LLMs can call to interact with the underlying operating system.

How to use mcp-server-commands?

mcp-server-commands can be integrated with LLM applications like Claude Desktop and Groq Desktop. Users need to configure their LLM application to recognize and use the mcp-server-commands server. This typically involves adding a JSON configuration snippet to the application's settings file, specifying the command to run the server (e.g., npx mcp-server-commands for the npm package or the path to a local build).

For development, users can install dependencies with npm install, build the server with npm run build, and use npm run watch for auto-rebuild during development.

To use with HTTP/OpenAPI, mcpo can be used to bridge STDIO and HTTP, allowing integration with tools like Open-WebUI.

Key Features of mcp-server-commands

• run_command tool: The core feature, allowing LLMs to execute arbitrary commands and scripts.
• STDOUT and STDERR capture: Returns the standard output and standard error of executed commands.
• Optional stdin parameter: Enables LLMs to pass input to commands (e.g., code to interpreters, text to file creation utilities).
• Compatibility: Designed to work with MCP-compatible LLM applications like Claude Desktop and Groq Desktop.
• Local Model Support: Provides guidance and suggestions for using local models with mcp-server-commands.
• Logging: Logs important messages to dedicated log files for debugging and monitoring.
• Debugging Tools: Includes an npm run inspector script for using the MCP Inspector to debug server interactions.

Use Cases of mcp-server-commands

• Automated Script Execution: LLMs can automate tasks by running shell scripts or commands directly.
• Code Generation and Execution: LLMs can generate code and then execute it using interpreters like Python, Bash, or Zsh.
• File Manipulation: LLMs can create or modify files on the system using commands like cat >> filename.
• System Information Retrieval: LLMs can query system information (e.g., hostname, ls -al).
• Integration with AI Chat Panels: Prompts can be used in AI chat panels (e.g., Zed's slash commands) to generate messages with command output.

FAQ from mcp-server-commands

• Security Warning: Users are strongly cautioned about the security implications of running arbitrary commands. It is recommended to use "Approve Once" in Claude Desktop and review each command, denying untrusted ones. The server should NOT be run with sudo.
• Permissions: Permissions are dictated by the user running the server.
• Local Model Behavior: Some local models may need coaxing (e.g., via system prompts) to use tools like run_command without hesitation.
• Logging Details: Logs are written to STDERR and can be made more verbose by adding --verbose to the server configuration arguments.
• Debugging Challenges: Debugging can be challenging due to STDIO communication, but the MCP Inspector is provided to assist.

Tools

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

Currently, just one command to rule them all!

• run_command - 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 code in 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_command - generate a prompt message with the command output

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_commands 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.