Simple Commands MCP Server

A configuration-driven Model Context Protocol (MCP) server that provides tools for executing developer commands and managing long-running processes. This server allows AI assistants to run predefined commands through a simple JSON configuration file.

Features

Configuration-driven: Add new tools by simply updating a JSON config file
Daemon Management: Handle long-running processes with automatic start/stop/status/logs commands
Auto-generated Controls: Each daemon automatically gets _start, _status, _stop, and _logs commands
Process Monitoring: Track PID, uptime, state, and capture output for all daemons
Automatic Cleanup: All processes are terminated when the MCP client disconnects
Cross-platform: Works on macOS, Linux, and Windows

Installation

Using npx (recommended)

No installation needed! Just run directly:

npx simple-commands-mcp @config.json

Global Installation

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

Local Development

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

Usage

Basic Usage

Create a config.json file with your tool definitions:

{
  "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
    }
  ]
}

Then run the MCP server:

npx simple-commands-mcp @config.json

Configuration Options

Each tool in the configuration has the following properties:

name (string, required): Unique identifier for the tool
description (string, required): Human-readable description of what the tool does
command (string, required): The shell command to execute
daemon (boolean, required): Set to true for long-running processes, false for one-shot commands

Daemon Tools

When you set daemon: true for a tool, the server automatically creates four commands:

{name}_start: Start the daemon process
{name}_status: Get current status, PID, uptime, and recent output
{name}_stop: Stop the daemon process
{name}_logs: Get the last N lines of output (default: 50)

Example: A tool named dev_server with daemon: true will create:

dev_server_start
dev_server_status
dev_server_stop
dev_server_logs

Examples

Simple Commands Configuration

{
  "tools": [
    {
      "name": "git_status",
      "description": "Show git repository status",
      "command": "git status",
      "daemon": false
    },
    {
      "name": "run_tests",
      "description": "Run test suite",
      "command": "npm test",
      "daemon": false
    },
    {
      "name": "build_project",
      "description": "Build the project",
      "command": "npm run build",
      "daemon": false
    }
  ]
}

Development Environment Configuration

{
  "tools": [
    {
      "name": "frontend",
      "description": "Frontend development server with hot reload",
      "command": "npm run dev:frontend",
      "daemon": true
    },
    {
      "name": "backend",
      "description": "Backend API server",
      "command": "npm run dev:backend",
      "daemon": true
    },
    {
      "name": "database",
      "description": "Local database server",
      "command": "docker-compose up db",
      "daemon": true
    },
    {
      "name": "migrate",
      "description": "Run database migrations",
      "command": "npm run db:migrate",
      "daemon": false
    }
  ]
}

MCP Client Configuration

To use this server with an MCP client (like Claude Desktop), add it to your MCP settings:

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

Working Directory

Commands are executed in the directory where you run the MCP server. To run commands in a specific directory:

Start the server from that directory:
cd /path/to/project npx simple-commands-mcp @config.json
Or use absolute paths in your commands:
{ "name": "project_build", "description": "Build the project", "command": "cd /path/to/project && npm run build", "daemon": false }

Troubleshooting

Server won't start

Ensure Node.js 18+ is installed: node --version
Check that your config file is valid JSON
Make sure the config file path is correct and prefixed with @

Commands fail to execute

Verify commands work when run manually from the same directory
Check that required dependencies are in PATH
Review the server logs for error messages

Daemon processes not stopping

The server automatically tracks and terminates all daemon processes when:
- The MCP client disconnects
- The server receives SIGINT/SIGTERM
- You use the {name}_stop command
Use Ctrl+C to gracefully shutdown the server and all daemons

Development

Building from Source

npm install
npm run build

Running in Development Mode

npm run dev

Project Structure

simple-commands-mcp/
├── src/
│   ├── cli.ts           # CLI entry point for npx
│   ├── server.ts        # Main MCP server
│   ├── types.ts         # TypeScript type definitions
│   ├── logger.ts        # Logging utilities
│   ├── processManager.ts # Daemon process management
│   └── toolExecutor.ts  # Command execution logic
├── dist/                # Compiled JavaScript (generated)
├── config.json          # Example configuration
├── package.json         # Package metadata and scripts
└── tsconfig.json        # TypeScript configuration

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and feature requests, please use the GitHub Issues page.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables AI assistants to execute predefined developer commands and manage long-running processes through a JSON configuration file. Supports both one-shot commands and daemon processes with automatic process lifecycle management.

Related MCP Servers

CodeSavant
twolven
-
security
A
license
-
quality
Provides code manipulation, execution, and version control capabilities. It allows AI assistants to read, write, and execute code while maintaining a history of changes.
Last updated -
9
MIT License
JSON Resume MCP Serverofficial
jsonresume
A
security
A
license
A
quality
A server that enhances AI assistants with the ability to update your JSON Resume by analyzing your coding projects, automatically extracting skills and generating professional descriptions.
Last updated -
320
55
The Unlicense
Divide and Conquer MCP Server
landicefu
A
security
A
license
A
quality
Enables AI agents to break down complex tasks into manageable pieces using a structured JSON format with task tracking, context preservation, and progress monitoring capabilities.
Last updated -
15
388
6
MIT License
Hi-AI
su-record
A
security
F
license
A
quality
A simple AI development tool that helps users interact with AI through natural language commands, offering 29 tools across thinking, memory, browser, code quality, planning, and time management capabilities.
Last updated -
33
5

View all related MCP servers

Simple Commands MCP Server