Mcp Server Commands

What is Mcp Server Commands about?

Enables large language models to request execution of shell commands through the run_command tool, returning the command's output and error streams. Designed for integration with Claude Desktop, Groq Desktop, and other MCP clients.

How to use Mcp Server Commands?

1. Install the npm package (or use the published package).\
2. Build the project with npm run build (if using source).\
3. Configure the MCP client to point to the server using an npx command.\
4. In the LLM chat, invoke the run_command tool with the desired command, optionally providing stdin.

Key Features

• Single run_command tool supporting any shell command (e.g., hostname, ls -al, python).\
• Returns both STDOUT and STDERR as text.\
• Optional stdin allows piping code or creating files via commands like cat >> file.txt.\
• Simple npm‑based deployment with npx.\
• Supports HTTP/OpenAPI via the mcpo bridge for web UI integration.\
• Verbose logging and inspection tools for debugging.

Use Cases

• Automating code generation and execution workflows for AI assistants.\
• Providing sandboxed command execution in Claude Desktop or Groq Desktop environments.\
• Enabling local model setups (e.g., Ollama) to run commands through LLM prompts.\
• Bridging MCP servers to web interfaces like Open‑WebUI via mcpo.

FAQ

Q: Do I need root privileges?
A: No. Run the server as a regular user and avoid sudo for security.

Q: How does logging work?
A: Logs are written to STDERR and captured by the client (e.g., Claude Desktop). Use --verbose to increase detail.

Q: Can I run the server over HTTP?
A: Yes, by using mcpo to expose an OpenAPI‑compatible endpoint.

Q: Is there a way to debug communication?
A: Use the MCP Inspector via npm run inspector for a browser‑based debugging UI.

Q: What models work best with this server?
A: Any model that can emit tool calls, such as Claude Sonnet 3.5, OpenHands LM, DevStral, or Qwen2.5‑Coder.

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.