inercia/MCPShell

The **MCPShell** is a tool that allows LLMs to safely execute **command-line tools**
through the **Model Context Protocol (MCP)**.
It provides a secure bridge between LLMs and operating system commands.
Features
- **Flexible command execution**: Run any shell commands as MCP tools,
with parameter substitution through templates.
- **Configuration-based tool definitions**: Define tools in YAML with parameters,
constraints, and output formatting.
- **Security through constraints**: Validate tool parameters using CEL expressions
before execution, as well as optional **sanboxed environments**
for running commands.
- **Quick proptotyping of MCP tools**: just add some shell code and use it as
a MCP tool in your LLM.
- **Simple integration**: Works with any LLM client supporting the MCP protocol
(ie, Cursor, VSCode, Witsy...)
Quick Start
Imagine you want Cursor (or some other MCP client) help you with your
space problems in your hard disk.
1. Create a configuration file /my/example.yaml defining your tools:
Take a look at the examples directory for more sophisticated and useful examples.
Maybe you prefer to let the LLM know about your Kubernetes cluster with
kubectl?
Or let it run some AWS CLI commands?
1. Configure the MCP server in Cursor (or in any other LLM client with support for MCP)
For example, for Cursor, create .cursor/mcp.json:
You can also use relative paths and omit the .yaml extension:
This will look for example.yaml in the tools directory (~/.mcpshell/tools/ by default).
See more details on how to configure Cursor or
Visual Studio Code. Other LLMs with support for MCPs
should be configured in a similar way.
1. Make sure your MCP client is refreshed (Cursor should recognize it automatically the
firt time, but any change in the config file will require a refresh).
1. Ask your LLM some questions it should be able to answer with the new tool. For example:
_"I'm running out of space in my hard disk. Could you help me finding the problem?"_.
Usage and Configuration
Take a look at all the command in this document.
Configuration files use a YAML format defined here.
See the this directory for some examples.
For deploying MCPShell in containers and Kubernetes, see the Container Deployment Guide.
Agent Mode
For AI agent functionality that connects LLMs directly to tools, see the
**Don** project. Don provides:
- Direct LLM connectivity without requiring a separate MCP client
- RAG (Retrieval-Augmented Generation) support
- Multi-agent architecture
- Uses MCPShell's tool configuration format
Security Considerations
So you will probably thing