📌Overview

Purpose: The framework is designed to enable integration of command execution capabilities within a language model interface, allowing users to run system commands and scripts seamlessly.

Overview: This framework allows language models, like Claude, to execute various commands and scripts directly, enhancing their usability and interaction with the user environment. The integration supports both single command execution and the running of full scripts, providing a versatile tool for developers.

Key Features:

• Command Execution: Enables the execution of simple system commands via run_command, returning output text for further interaction. This allows users to gain real-time insights from system operations.

• Script Execution: Allows users to pass scripts through run_script, facilitating the execution of complex code directly within the framework. This feature supports multiple scripting languages and enhances the model's creative capabilities in generating and handling code.

---

Tools

Tools are for LLMs to request, e.g., Claude Desktop app. Claude Sonnet 3.5 intelligently uses both tools.

• run_command - run a command, e.g., hostname, ls -al, or echo "hello world".
  • Returns STDOUT and STDERR as text
• run_script - run a script (e.g., fish, bash, zsh, python)
  • Let your LLM run the code it writes!
  • Script is passed over STDIN
  • run_script == run_command + script over STDIN
  • Claude has been creative with this, e.g., using cat as the interpreter to create new files!

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.

Prompts

Prompts are for users to include in chat history, e.g., 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

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)

{
  "mcpServers": {
    "mcp-server-commands": {
      "command": "/path/to/mcp-server-commands/build/index.js"
    }
  }
}

Logging

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

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

Logs are written to STDERR because Claude Desktop routes STDERR to log files. In the future, well-formatted log messages may be written over the STDIO transport to the MCP client.

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. Use the MCP Inspector, available as a package script:

npm run inspector

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