{"id":"8a19c2ba-81db-4331-99a9-f1c4781dc3e6","slug":"inercia-mcpshell","kind":"mcp","name":"MCPShell","summary":"Use shell scripts as MCP tools","owner":"inercia","repoUrl":"https://github.com/inercia/MCPShell","license":"MIT","licenseTier":"permissive","trust":"community","stars":72,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-05-10T14:18:45.000Z","addedAt":"2026-10-14T05:24:04.515Z","logoUrl":"https://avatars.githubusercontent.com/u/1841612?u=3016078936d58200626fd3a6e96748b5cc0a7f19&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T13:47:20.996Z","sample":false,"url":"https://conduits.dev/tools/inercia-mcpshell","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# MCPShell\n\n<p align=\"center\">\n  <img src=\"docs/logo.png\" alt=\"banner\" width=\"300\"/>\n</p>\n\nThe **MCPShell** is a tool that allows LLMs to safely execute **command-line tools**\nthrough the [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io/).\nIt provides a secure bridge between LLMs and operating system commands.\n\n## Features\n\n- **Flexible command execution**: Run any shell commands as MCP tools,\n  with parameter substitution through templates.\n- **Configuration-based tool definitions**: Define tools in YAML with parameters,\n  constraints, and output formatting.\n- **Security through constraints**: Validate tool parameters using CEL expressions\n  before execution, as well as optional [**sanboxed environments**](docs/config-runners.md)\n  for running commands.\n- **Quick proptotyping of MCP tools**: just add some shell code and use it as\n  a MCP tool in your LLM.\n- **Simple integration**: Works with any LLM client supporting the MCP protocol\n  (ie, Cursor, VSCode, Witsy...)\n\n## Quick Start\n\nImagine you want Cursor (or some other MCP client) help you with your\nspace problems in your hard disk.\n\n1. Create a configuration file `/my/example.yaml` defining your tools:\n\n   ```yaml\n   mcp:\n     description: |\n       Tool for analyzing disk usage to help identify what's consuming space.\n     run:\n       shell: bash\n     tools:\n       - name: \"disk_usage\"\n         description: \"Check disk usage for a directory\"\n         params:\n           directory:\n             type: string\n             description: \"Directory to analyze\"\n             required: true\n           max_depth:\n             type: number\n             description: \"Maximum depth to analyze (1-3)\"\n             default: 2\n         constraints:\n           - \"directory.startsWith('/')\"  # Must be absolute path\n           - \"!directory.contains('..')\"  # Prevent directory traversal\n           - \"max_depth >= 1 && max_depth <= 3\"  # Limit recursion depth\n           - \"directory.matches('^[\\\\w\\\\s./\\\\-_]+$')\"  # Only allow safe path characters, prevent command injection\n         run:\n           command: |\n             du -h --max-depth={{ .max_depth }} {{ .directory }} | sort -hr | head -20\n         output:\n           prefix: |\n             Disk Usage Analysis (Top 20 largest directories):\n   ```\n\n   Take a look at the [examples directory](examples) for more sophisticated and useful examples.\n   Maybe you prefer to let the LLM know about your Kubernetes cluster with\n   [kubectl](examples/kubectl-ro.yaml)?\n   Or let it run some [AWS CLI](examples/aws-networking-ro.yaml) commands?\n\n1. Configure the MCP server in Cursor (or in any other LLM client with support for MCP)\n\n   For example, for Cursor, create `.cursor/mcp.json`:\n\n   ```json\n   {\n       // you need the \"go\" command available\n       \"mcpServers\": {\n           \"mcp-cli-examples\": {\n               \"command\": \"go\",\n               \"args\": [\n                  \"run\", \"github.com/inercia/MCPShell@v0.1.8\",\n                  \"mcp\", \"--tools\", \"/my/example.yaml\",\n                  \"--logfile\", \"/some/path/mcpshell/example.log\"\n               ]\n           }\n       }\n   }\n   ```\n\n   You can also use relative paths and omit the `.yaml` extension:\n\n   ```json\n   {\n       \"mcpServers\": {\n           \"mcp-cli-examples\": {\n               \"command\": \"go\",\n               \"args\": [\n                  \"run\", \"github.com/inercia/MCPShell@v0.1.8\",\n                  \"mcp\", \"--tools\", \"example\",\n                  \"--logfile\", \"/some/path/mcpshell/example.log\"\n               ]\n           }\n       }\n   }\n   ```\n\n   This will look for `example.yaml` in the tools directory (`~/.mcpshell/tools/` by default).\n\n   See more details on how to configure [Cursor](docs/usage-cursor.md) or\n   [Visual Studio Code](docs/usage-vscode.md). Other LLMs with support for MCPs\n   should be configured in a similar way.\n\n1. Make sure your MCP client is refreshed (Cursor should recognize it automatically the\n   firt time, but any change in the config file will require a refresh).\n\n1. Ask your LLM some questions it should be able to answer with the new tool. For example:\n   _\"I'm running out of space in my hard disk. Could you help me finding the problem?\"_.\n\n## Usage and Configuration\n\nTake a look at all the command in [this document](docs/usage.md).\n\nConfiguration files use a YAML format defined [here](docs/config.md).\nSee the [this directory](examples) for some examples.\n\nFor deploying MCPShell in containers and Kubernetes, see the [Container Deployment Guide](docs/usage-containers.md).\n\n## Agent Mode\n\nFor AI agent functionality that connects LLMs directly to tools, see the\n[**Don**](https://github.com/inercia/don) project. Don provides:\n\n- Direct LLM connectivity without requiring a separate MCP client\n- RAG (Retrieval-Augmented Generation) support\n- Multi-agent architecture\n- Uses MCPShell's tool configuration format\n\n## Security Considerations\n\nSo you will probably thing\n_\"this AI has helped me finding all those big files. What if I create another tool for removing files?\"_.\n**Don't do that!**.\n\n- Limit the scope of these tools to **read-only actions**, do not give the LLM the power to change things.\n- Use **constraints** to limit command execution to safe parameters\n- Consider using a [**sanboxed environment**](docs/config-runners.md) for running commands.\n- Review all command templates for potential injection vulnerabilities\n- Only expose tools that are safe for external use\n- All of the above!\n\nPlease read the [Security Considerations](docs/security.md) document before using this software.\n\n## Contributing\n\nContributions are welcome! Take a look at the [development guide](docs/development.md).\nPlease open an issue or submit a pull request on GitHub.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n"}