-
securityA
license-
qualityProvides 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
Enables execution of Docker commands including docker-compose operations for managing containers and services
Provides tools for executing Git commands to check repository status and perform version control operations
Allows execution of npm commands for package management, running scripts, building projects, and testing
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_logscommandsProcess 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 tooldescription(string, required): Human-readable description of what the tool doescommand(string, required): The shell command to executedaemon(boolean, required): Set totruefor long-running processes,falsefor 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_startdev_server_statusdev_server_stopdev_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.jsonOr 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 --versionCheck 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}_stopcommand
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
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
JSON Resume MCP Serverofficial
AsecurityAlicenseAqualityA 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 -3157The Unlicense- AsecurityAlicenseAqualityEnables 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 -15496MIT License