{"id":28512220,"url":"https://github.com/inercia/mcpshell","last_synced_at":"2025-06-29T11:07:28.350Z","repository":{"id":292530119,"uuid":"981179719","full_name":"inercia/MCPShell","owner":"inercia","description":"Use shell scripts as MCP tools","archived":false,"fork":false,"pushed_at":"2025-05-19T09:07:57.000Z","size":3644,"stargazers_count":21,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-09T00:40:02.228Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inercia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-10T14:18:45.000Z","updated_at":"2025-06-07T09:17:54.000Z","dependencies_parsed_at":"2025-05-13T20:43:28.979Z","dependency_job_id":"56f014ed-30c8-46c9-bf3c-fe0fe27fdf57","html_url":"https://github.com/inercia/MCPShell","commit_stats":null,"previous_names":["inercia/mcp-cli-adapter","inercia/mcpshell"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/inercia/MCPShell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inercia%2FMCPShell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inercia%2FMCPShell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inercia%2FMCPShell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inercia%2FMCPShell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inercia","download_url":"https://codeload.github.com/inercia/MCPShell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inercia%2FMCPShell/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262581374,"owners_count":23331913,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-09T00:37:11.118Z","updated_at":"2025-06-29T11:07:28.329Z","avatar_url":"https://github.com/inercia.png","language":"Go","funding_links":[],"categories":["Utilities","Command Line","📦 Other"],"sub_categories":["Development Tools","How to Submit"],"readme":"# MCPShell\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/logo.png\" alt=\"banner\" width=\"300\"/\u003e\n\u003c/p\u003e\n\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 \u003e= 1 \u0026\u0026 max_depth \u003c= 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\n2. 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.5\",\n                  \"mcp\", \"--config\", \"/my/example.yaml\",\n                  \"--logfile\", \"/some/path/mcpshell/example.log\"\n               ]\n           }\n       }\n   }\n   ```\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\n3. 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).\n4. 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\n## Agent Mode\n\nMCPShell can also be run in agent mode, providing direct connectivity between Large Language Models\n(LLMs) and your command-line tools without requiring a separate MCP client. In this mode,\nMCPShell connects to an OpenAI-compatible API (including local LLMs like Ollama), makes your\ntools available to the model, executes requested tool operations, and manages the conversation flow.\nThis enables the creation of specialized AI assistants that can autonomously perform system tasks\nusing the tools you define in your configuration. The agent mode supports both interactive\nconversations and one-shot executions, and allows you to define system and user prompts directly\nin your configuration files.\n\nFor detailed information on using agent mode, see the [Agent Mode documentation](docs/usage-agent.md).\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finercia%2Fmcpshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finercia%2Fmcpshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finercia%2Fmcpshell/lists"}