Skip to content
Back to search

cli-mcp-server

Command line interface for MCP clients with secure execution and customizable security policies

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mladensu--cli-mcp-server/badge.svg)](/listings/mladensu--cli-mcp-server)

HTML

<a href="/listings/mladensu--cli-mcp-server"><img src="/api/listings/mladensu--cli-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

To install CLI MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/protocol/cli-mcp-server):

npx @smithery/cli install cli-mcp-server --client claude

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 232 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # CLI MCP Server
  2. ---
  3. A secure Model Context Protocol (MCP) server implementation for executing controlled command-line operations with
  4. comprehensive security features.
  5. ![License](https://img.shields.io/badge/license-MIT-blue.svg)
  6. ![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
  7. ![MCP Protocol](https://img.shields.io/badge/MCP-Compatible-green)
  8. [![smithery badge](https://smithery.ai/badge/cli-mcp-server)](https://smithery.ai/protocol/cli-mcp-server)
  9. [![Python Tests](https://github.com/MladenSU/cli-mcp-server/actions/workflows/python-tests.yml/badge.svg)](https://github.com/MladenSU/cli-mcp-server/actions/workflows/python-tests.yml)
  10. <a href="https://glama.ai/mcp/servers/q89277vzl1"><img width="380" height="200" src="https://glama.ai/mcp/servers/q89277vzl1/badge" /></a>
  11. ---
  12. # Table of Contents
  13. 1. [Overview](#overview)
  14. 2. [Features](#features)
  15. 3. [Configuration](#configuration)
  16. 4. [Available Tools](#available-tools)
  17. - [run_command](#run_command)
  18. - [show_security_rules](#show_security_rules)
  19. 5. [Usage with Claude Desktop](#usage-with-claude-desktop)
  20. - [Development/Unpublished Servers Configuration](#developmentunpublished-servers-configuration)
  21. - [Published Servers Configuration](#published-servers-configuration)
  22. 6. [Security Features](#security-features)
  23. 7. [Error Handling](#error-handling)
  24. 8. [Development](#development)
  25. - [Prerequisites](#prerequisites)
  26. - [Building and Publishing](#building-and-publishing)
  27. - [Debugging](#debugging)
  28. 9. [License](#license)
  29. ---
  30. ## Overview
  31. This MCP server enables secure command-line execution with robust security measures including command whitelisting, path
  32. validation, and execution controls. Perfect for providing controlled CLI access to LLM applications while maintaining security.
  33. ## Features
  34. - 🔒 Secure command execution with strict validation
  35. - ⚙️ Configurable command and flag whitelisting with 'all' option
  36. - 🛡️ Path traversal prevention and validation
  37. - 🚫 Shell operator injection protection
  38. - ⏱️ Execution timeouts and length limits
  39. - 📝 Detailed error reporting
  40. - 🔄 Async operation support
  41. - 🎯 Working directory restriction and validation
  42. ## Configuration
  43. Configure the server using environment variables:
  44. | Variable | Description | Default |
  45. |---------------------|------------------------------------------------------|-------------------|
  46. | `ALLOWED_DIR` | Base directory for command execution (Required) | None (Required) |
  47. | `ALLOWED_COMMANDS` | Comma-separated list of allowed commands or 'all' | `ls,cat,pwd` |
  48. | `ALLOWED_FLAGS` | Comma-separated list of allowed flags or 'all' | `-l,-a,--help` |
  49. | `MAX_COMMAND_LENGTH`| Maximum command string length | `1024` |
  50. | `COMMAND_TIMEOUT` | Command execution timeout (seconds) | `30` |
  51. | `ALLOW_SHELL_OPERATORS` | Allow shell operators (&&, \|\|, \|, >, etc.) | `false` |
  52. Note: Setting `ALLOWED_COMMANDS` or `ALLOWED_FLAGS` to 'all' will allow any command or flag respectively.
  53. ## Installation
  54. To install CLI MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/protocol/cli-mcp-server):
  55. ```bash
  56. npx @smithery/cli install cli-mcp-server --client claude
  57. ```
  58. ## Available Tools
  59. ### run_command
  60. Executes whitelisted CLI commands within allowed directories.
  61. **Input Schema:**
  62. ```json
  63. {
  64. "command": {
  65. "type": "string",
  66. "description": "Single command to execute (e.g., 'ls -l' or 'cat file.txt')"
  67. }
  68. }
  69. ```
  70. **Security Notes:**
  71. - Shell operators (&&, |, >, >>) are not supported by default, but can be enabled with `ALLOW_SHELL_OPERATORS=true`
  72. - Commands must be whitelisted unless ALLOWED_COMMANDS='all'
  73. - Flags must be whitelisted unless ALLOWED_FLAGS='all'
  74. - All paths are validated to be within ALLOWED_DIR
  75. ### show_security_rules
  76. Displays current security configuration and restrictions, including:
  77. - Working directory
  78. - Allowed commands
  79. - Allowed flags
  80. - Security limits (max command length and timeout)
  81. ## Usage with Claude Desktop
  82. Add to your `~/Library/Application\ Support/Claude/claude_desktop_config.json`:
  83. > Development/Unpublished Servers Configuration
  84. ```json
  85. {
  86. "mcpServers": {
  87. "cli-mcp-server": {
  88. "command": "uv",
  89. "args": [
  90. "--directory",
  91. "<path/to/the/repo>/cli-mcp-server",
  92. "run",
  93. "cli-mcp-server"
  94. ],
  95. "env": {
  96. "ALLOWED_DIR": "</your/desired/dir>",
  97. "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
  98. "ALLOWED_FLAGS": "-l,-a,--help,--version",
  99. "MAX_COMMAND_LENGTH": "1024",
  100. "COMMAND_TIMEOUT": "30",
  101. "ALLOW_SHELL_OPERATORS": "false"
  102. }
  103. }
  104. }
  105. }
  106. ```
  107. > Published Servers Configuration
  108. ```json
  109. {
  110. "mcpServers": {
  111. "cli-mcp-server": {
  112. "command": "uvx",
  113. "args": [
  114. "cli-mcp-server"
  115. ],
  116. "env": {
  117. "ALLOWED_DIR": "</your/desired/dir>",
  118. "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
  119. "ALLOWED_FLAGS": "-l,-a,--help,--version",
  120. "MAX_COMMAND_LENGTH": "1024",
  121. "COMMAND_TIMEOUT": "30",
  122. "ALLOW_SHELL_OPERATORS": "false"
  123. }
  124. }
  125. }
  126. }
  127. ```
  128. > In case it's not working or showing in the UI, clear your cache via `uv clean`.
  129. ## Security Features
  130. - ✅ Command whitelist enforcement with 'all' option
  131. - ✅ Flag validation with 'all' option
  132. - ✅ Path traversal prevention and normalization
  133. - ✅ Shell operator blocking (with opt-in support via `ALLOW_SHELL_OPERATORS=true`)
  134. - ✅ Command length limits
  135. - ✅ Execution timeouts
  136. - ✅ Working directory restrictions
  137. - ✅ Symlink resolution and validation
  138. ## Error Handling
  139. The server provides detailed error messages for:
  140. - Security violations (CommandSecurityError)
  141. - Command timeouts (CommandTimeoutError)
  142. - Invalid command formats
  143. - Path security violations
  144. - Execution failures (CommandExecutionError)
  145. - General command errors (CommandError)
  146. ## Development
  147. ### Prerequisites
  148. - Python 3.10+
  149. - MCP protocol library
  150. ### Building and Publishing
  151. To prepare the package for distribution:
  152. 1. Sync dependencies and update lockfile:
  153. ```bash
  154. uv sync
  155. ```
  156. 2. Build package distributions:
  157. ```bash
  158. uv build
  159. ```
  160. > This will create source and wheel distributions in the `dist/` directory.
  161. 3. Publish to PyPI:
  162. ```bash
  163. uv publish --token {{YOUR_PYPI_API_TOKEN}}
  164. ```
  165. ### Debugging
  166. Since MCP servers run over stdio, debugging can be challenging. For the best debugging
  167. experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
  168. You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with
  169. this command:
  170. ```bash
  171. npx @modelcontextprotocol/inspector uv --directory {{your source code local directory}}/cli-mcp-server run cli-mcp-server
  172. ```
  173. Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
  174. ## License
  175. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  176. ---
  177. For more information or support, please open an issue on the project repository.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.