A powerful Model Context Protocol (MCP) server that enables AI assistants to execute command-line tools through a flexible, configuration-driven interface. Turn any command-line utility into an AI-accessible tool with simple JSON configuration.
- 🔧 Configuration-Driven: Define commands via JSON configuration files
- 🛡️ Type-Safe: Built with TypeScript and comprehensive validation using Zod and AJV
- 📋 Flexible Arguments: Support for string, number, and boolean arguments with defaults
- 🔍 Debug Support: Comprehensive logging with debug and verbose modes
- ⚡ Fast & Reliable: Built on the official MCP SDK with robust error handling
- 🌐 Cross-Platform: Works on Windows, macOS, and Linux
# Install globally via npm
npm install -g mcp-cli- Create a configuration file (
config.json):
{
"version": "1.0",
"commands": [
{
"name": "echo",
"description": "Echo a message to the console",
"command": "echo",
"arguments": [
{
"name": "message",
"description": "The message to echo",
"type": "string",
"required": true
}
]
},
{
"name": "list-files",
"description": "List files in a directory",
"command": "dir",
"arguments": [
{
"name": "path",
"description": "The directory path to list",
"type": "string",
"required": false,
"defaultValue": "."
}
]
}
]
}- Run the MCP server:
# Using config file
mcp-cli --config-file ./config.json
# Using inline JSON config
mcp-cli --config '{"version":"1.0","commands":[...]}'
# With environment variable (config file path)
set MCP_CLI_CONFIG_PATH=./config.json
mcp-cli
# With environment variable (raw JSON config)
set MCP_CLI_CONFIG_JSON={"version":"1.0","commands":[{"name":"echo","description":"Echo a message","command":"echo","arguments":[{"name":"message","description":"The message to echo","type":"string","required":true}]}]}
mcp-cli
# Streaming config via pipe (Windows)
type config.json | mcp-cli
# Streaming config via pipe (Unix/Linux/macOS)
cat config.json | mcp-cli- Connect your AI assistant to the MCP server and start executing commands!
{
"version": "1.0",
"commands": [
{
"name": "command-name",
"description": "Description of what this command does",
"command": "actual-cli-command",
"arguments": [
{
"name": "arg-name",
"description": "Argument description",
"type": "string|number|boolean",
"required": true|false,
"defaultValue": "optional-default"
}
]
}
]
}| Property | Type | Required | Description |
|---|---|---|---|
name |
string | ✅ | Argument name |
description |
string | ✅ | Human-readable description |
type |
"string" | "number" | "boolean" |
✅ | Argument data type |
required |
boolean | ✅ | Whether the argument is mandatory |
defaultValue |
string | number | boolean | ❌ | Default value if not provided |
Interested in contributing? Check out our Contributing Guide for development setup, build instructions, and guidelines.
{
"version": "1.0",
"commands": [
{
"name": "git-status",
"description": "Check Git repository status",
"command": "git status",
"arguments": []
},
{
"name": "git-commit",
"description": "Commit changes with a message",
"command": "git commit",
"arguments": [
{
"name": "message",
"description": "Commit message",
"type": "string",
"required": true
},
{
"name": "all",
"description": "Stage all changes",
"type": "boolean",
"required": false,
"defaultValue": false
}
]
}
]
}{
"version": "1.0",
"commands": [
{
"name": "system-info",
"description": "Display system information",
"command": "systeminfo",
"arguments": []
},
{
"name": "disk-usage",
"description": "Show disk usage",
"command": "dir",
"arguments": [
{
"name": "drive",
"description": "Drive letter to check",
"type": "string",
"required": false,
"defaultValue": "C:\\"
}
]
}
]
}Interested in contributing? Check out our Contributing Guide for development setup, build instructions, and guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with the Model Context Protocol SDK
- Powered by Rush Stack tools
- Validation provided by Zod and AJV
- Model Context Protocol - The protocol specification
- MCP SDK - Official TypeScript SDK
- Claude Desktop - AI assistant with MCP support
Made with ❤️ for the AI community