ShellMCP

Expose Shell Commands as MCP Tools

ShellMCP is a powerful tool that allows you to easily create Model Context Protocol (MCP) servers by exposing shell commands as structured tools. Instead of granting AI agents full shell access (which poses security risks), ShellMCP enables you to expose only the specific commands you trust, allowing agents to work autonomously with a predefined set of safe operations.

Define your tools in YAML, and ShellMCP generates and runs a complete FastMCP server for you.

Quick Start

# Install ShellMCP
pip install shellmcp

# Run a built-in MCP server directly
shellmcp run basics

# Or create a custom server configuration
shellmcp new --name "my-server" --desc "My custom MCP server"

# Add a tool interactively
shellmcp add-tool my-server.yml

# Validate the configuration
shellmcp validate my-server.yml

# Generate the FastMCP server
shellmcp generate my-server.yml

# Or run directly from a YAML file
shellmcp run --config_file my-server.yml

Features

• 🚀 Simple YAML Configuration: Define tools and resources in clean YAML
• 🔧 Interactive CLI: Add tools and resources with guided prompts
• 📝 Template Support: Use Jinja2 templates for dynamic command generation
• ✅ Validation: Built-in configuration validation and error checking
• 🎯 FastMCP Integration: Generates and runs production-ready FastMCP servers
• 📦 Built-in Configurations: Pre-configured servers ready to run
• 🔒 Security-First: Expose only trusted commands to AI agents
• 🎨 Flexible: Support for tools and resources with reusable arguments
• ⚡ Instant Execution: Run servers directly from YAML without generating files

Example

server:
  name: "file-manager"
  desc: "File system operations"
  version: "1.0.0"

args:
  path_arg:
    help: "Directory path"
    type: string
    default: "."
  pattern_arg:
    help: "Search pattern"
    type: string

tools:
  list_files:
    cmd: "ls -la {{path}}"
    desc: "List files in a directory"
    args:
      - name: path
        ref: path_arg
  
  search_files:
    cmd: "find {{path}} -name '{{pattern}}' -type f"
    desc: "Search for files matching a pattern"
    args:
      - name: path
        ref: path_arg
      - name: pattern
        ref: pattern_arg

resources:
  system_info:
    uri: "file:///tmp/system-info.txt"
    name: "System Information"
    description: "Current system status and info"
    cmd: "uname -a && df -h"
    mime_type: "text/plain"

prompts:
  file_analysis:
    name: "File Analysis Assistant"
    description: "Helps analyze file system contents"
    template: |
      Analyze the following file system information:
      
      Current directory: {{path}}
      Files: {{file_list}}
      
      Provide insights about the file structure and suggest any organization improvements.
    args:
      - name: path
        help: "Directory path to analyze"
        type: string
        default: "."
      - name: file_list
        help: "List of files to analyze"
        type: string

CLI Commands

ShellMCP provides several commands to help you create and manage MCP servers:

shellmcp run

Run an MCP server directly from a built-in configuration or YAML file.

# Run a built-in configuration
shellmcp run basics

# Run from a custom YAML file
shellmcp run --config_file my-server.yml

Built-in configurations:

• basics: Basic shell operations for file system, process management, and system information

The basics configuration includes tools for:

• File operations (list, find, copy, move, delete)
• Directory management (create, remove, navigate)
• Process management (list, kill processes)
• System information (memory, disk, network)
• Text operations (read, write, search)
• Resources for system status and environment info

shellmcp new

Create a new server configuration file.

shellmcp new --name "my-server" --desc "My custom MCP server" --version "1.0.0"

shellmcp add-tool

Add a new tool to an existing configuration.

shellmcp add-tool my-server.yml --name "list-files" --cmd "ls -la {{path}}" --desc "List files in directory"

shellmcp add-resource

Add a new resource to an existing configuration.

shellmcp add-resource my-server.yml --name "system-info" --uri "file:///tmp/system-info.txt" --resource-name "System Information"

shellmcp add-prompt

Add a new prompt to an existing configuration.

shellmcp add-prompt my-server.yml --name "file-analysis" --prompt-name "File Analysis Assistant"

shellmcp validate

Validate a YAML configuration file.

shellmcp validate my-server.yml --verbose

shellmcp generate

Generate a FastMCP server from YAML configuration.

Default behavior: Creates a subdirectory with the server name to prevent overwriting existing files.

# Generate with default output directory (creates ./my-server/ subdirectory)
shellmcp generate my-server.yml --verbose

# Generate with custom output directory
shellmcp generate my-server.yml --output-dir ./output --verbose

Documentation

• YAML Specification

License

MIT License - see LICENSE for details.