Simple Commands

You run a configuration-driven MCP server that lets you define and execute developer commands, manage long-running daemons, and monitor their status from a single, consistent interface. This server adapts to your needs by reading a JSON config and exposing ready-made controls for starting, stopping, checking status, and viewing logs for each daemon you define.

How to use

Connect an MCP client to this server and manage your tools from a central control panel. Create a JSON config that describes each tool you want to run, including whether it is a one-shot command or a long-running daemon. For every daemon you enable, you gain automatic controls to start, check status, stop, and fetch logs. You can run commands from any working directory, and the server will keep track of PID, uptime, and recent output for each daemon. When the MCP client disconnects, all daemons are cleanly terminated to prevent orphaned processes.

How to install

Prerequisites: install Node.js 18 or later and npm. You will also need a JSON config file that defines your tools.

Step 1. Create your config file, for example config.json, with your tool definitions.

Step 2. Run the MCP server quickly without installing anything locally by using npx, pointing to your config file.

npx simple-commands-mcp @config.json

Step 3. (Optional) Install the MCP server globally and run from anywhere.

npm install -g simple-commands-mcp
 simple-commands-mcp @config.json

Step 4. (Optional) For local development, clone the project, install dependencies, build, and link for development use.

git clone https://github.com/yourusername/simple-commands-mcp.git
 cd simple-commands-mcp
 npm install
 npm run build
 npm link
 simple-commands-mcp @config.json

Configuration and tools you define

Define tools in a JSON file to describe what you want to run and whether it should run as a daemon.

For the basic usage example, you can include a one-shot command and a daemon, then let the server manage repeated starts and logs for the daemon.

{
  "tools": [
    {
      "name": "list_files",
      "description": "List files in current directory",
      "command": "ls -la",
      "daemon": false
    },
    {
      "name": "dev_server",
      "description": "Start development server",
      "command": "npm run dev",
      "daemon": true
    }
  ]
}

MCP client configuration

To connect this MCP server through a client, define the MCP server entry with an executable command and arguments. This allows the client to launch the server inside your environment.

{
  "mcpServers": {
    "simple-commands": {
      "command": "npx",
      "args": ["simple-commands-mcp", "@/path/to/your/config.json"]
    }
  }
}

Working directory and path considerations

Commands run by the MCP server execute in the directory where you started the server. If you need to run commands in a specific directory, either start the server from that directory or embed absolute paths in your command definitions.

Troubleshooting

If the server won’t start, ensure Node.js 18+ is installed and your config.json is valid JSON. Confirm the path to your config.json is correct and that you prefix it with @ when using certain runners.

If a command fails to execute, verify the command works when run manually from the same directory and ensure required dependencies are accessible in PATH.

If daemon processes don’t stop properly, the server will terminate all daemons automatically when the MCP client disconnects or when you issue the stop command for a daemon. You can also gracefully shut down the server with Ctrl+C to terminate all daemons.

Development

Build and run locally to contribute or test new features.

npm install
npm run build

npm run dev

Project structure

This project contains sources for the MCP server and example configurations to help you get started.

Available tools

list_files

List files in current directory

dev_server

Start development server

git_status

Show git repository status

run_tests

Run test suite

build_project

Build the project

frontend

Frontend development server with hot reload

backend

Backend API server

database

Local database server

migrate

Run database migrations