https://github.com/g0t4/mcp-server-commands
Model Context Protocol server to run commands
https://github.com/g0t4/mcp-server-commands
Last synced: 7 days ago
JSON representation
Model Context Protocol server to run commands
- Host: GitHub
- URL: https://github.com/g0t4/mcp-server-commands
- Owner: g0t4
- License: mit
- Created: 2024-11-29T02:39:02.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2024-12-21T05:03:20.000Z (4 months ago)
- Last Synced: 2025-04-09T18:16:11.581Z (7 days ago)
- Language: JavaScript
- Size: 186 KB
- Stars: 99
- Watchers: 2
- Forks: 20
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-list - g0t4/mcp-server-commands - server-commands?style=social)](https://github.com/g0t4/mcp-server-commands): Executes arbitrary commands and scripts via MCP. (Uncategorized / Uncategorized)
- awesome-mcp-servers - g0t4/mcp-server-commands - Run any command with `run_command` and `run_script` tools. (Legend / 🖥️ <a name="command-line"></a>Command Line)
- awesome-mcp-servers - g0t4/mcp-server-commands - Run any command with `run_command` and `run_script` tools. (Legend / 🖥️ <a name="command-line"></a>Command Line)
- awesome-mcp-servers - g0t4/mcp-server-commands - コマンドを実行し、その出力を含める。ツールとプロンプト。 (サーバー実装 / 🛠️ <a name="other-tools-and-integrations"></a>その他のツールと統合)
- awesome-mcp-servers - LLM Command Runner - Model Context Protocol server to run commands (Table of Contents / AI Services)
- awesome-mcp-servers - LLM Command Runner - Model Context Protocol server to run commands (Table of Contents / AI Services)
README
## Tools
Tools are for LLMs to request, i.e. Claude Desktop app. Claude Sonnet 3.5 intelligently uses both tools, I was pleasantly surprised.
- `run_command` - run a command, i.e. `hostname` or `ls -al` or `echo "hello world"` etc
- Returns STDOUT and STDERR as text
- `run_script` - run a script! (i.e. `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 pretty creative with this, i.e. 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`.
## 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:
```bash
npm install
```
Build the server:
```bash
npm run build
```
For development with auto-rebuild:
```bash
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](https://www.npmjs.com/package/mcp-server-commands) using this [workflow](https://github.com/g0t4/mcp-server-commands/actions)
```json
{
"mcpServers": {
"mcp-server-commands": {
"command": "npx",
"args": ["mcp-server-commands"]
}
}
}
```
### Use a local build (repo checkout)
```json
{
"mcpServers": {
"mcp-server-commands": {
// works b/c of shebang in index.js
"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 (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](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
```bash
npm run inspector
```
The Inspector will provide a URL to access debugging tools in your browser.