`mcp-this`

An MCP Server that dynamically exposes CLI/bash commands as tools and prompt templates through YAML configuration files.

mcp-this lets you turn any command-line tool into an MCP tool and create structured prompt templates that any MCP Client (e.g. Claude Desktop) can use. Instead of writing code, you simply define commands, prompts, and their parameters in YAML files, and the MCP Server makes them available to MCP Clients like Claude Desktop.

Core Value: Transform CLI commands into MCP tools and create reusable prompt templates using simple YAML configuration.

How It Works

Define tools (CLI commands) and prompts (AI templates) in YAML:

tools:
  get-current-time:
    description: |
      Display the current date and time in various formats.
      
      Examples:
      - get_current_time(format="iso") → 2025-05-18T17:17:39Z
      - get_current_time(format="readable") → Friday, May 18, 2025 5:17 PM
    execution:
      command: >-
        if [ "<<format>>" = "iso" ]; then 
          date -u +"%Y-%m-%dT%H:%M:%SZ"; 
        elif [ "<<format>>" = "readable" ]; then 
          date "+%A, %B %d, %Y %I:%M %p"; 
        else 
          echo "ISO: $(date -u +"%Y-%m-%dT%H:%M:%SZ")"; 
          echo "Readable: $(date "+%A, %B %d, %Y %I:%M %p")"; 
        fi
    parameters:
      format:
        description: "Time format: iso, readable, or empty for both"
        required: false

  system-info:
    description: Get basic system information
    execution:
      command: uname -a && echo "CPU: $(nproc) cores"
    parameters: {}

prompts:
  code-reviewer:
    description: Perform a thorough code review with best practices focus
    template: |
      Please review the following code with a focus on:
      - Code quality and best practices
      - Security vulnerabilities
      - Performance considerations
      {{#if focus_area}}- Special attention to: {{focus_area}}{{/if}}
      
      Code to review:
      {{code}}
      
      {{#if context}}Additional context: {{context}}{{/if}}
    arguments:
      code:
        description: Code to review
        required: true
      focus_area:
        description: Specific area to focus on (e.g., security, performance)
        required: false
      context:
        description: Additional context about the code
        required: false

Use in Claude Desktop:

{
  "mcpServers": {
    "mcp-this-custom": {
      "command": "uvx",
      "args": ["mcp-this", "--config-path", "/path/to/your-tools.yaml"]
    }
  }
}

That's it! Claude can now:

Execute your custom CLI tools (get-current-time, system-info)
Use your structured prompt templates (code-reviewer with guided arguments)

Quick Start

1. Install uvx

# Install uv (includes uvx)
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create Your First Tool

Create my-tools.yaml:

tools:
  web-scraper:
    description: Fetch a webpage and convert it to clean, readable text
    execution:
      command: curl -s '<<url>>' | lynx -dump -stdin
    parameters:
      url:
        description: URL of the webpage to fetch
        required: true

  find-large-files:
    description: Find files larger than specified size in a directory
    execution:
      command: find '<<directory>>' -type f -size +<<size>> -exec ls -lh {} \;
    parameters:
      directory:
        description: Directory to search
        required: true
      size:
        description: Minimum file size (e.g., 100M, 1G)
        required: true

2.1. Add AI Prompt Templates (Optional)

Enhance your my-tools.yaml with structured prompt templates:

tools:
  # ... your tools above ...

prompts:
  summarize-webpage:
    description: Generate a structured summary of webpage content
    template: |
      Please analyze the following webpage content and provide:
      
      1. **Main Topic**: What is this page about?
      2. **Key Points**: {{num_points}} most important points
      3. **Target Audience**: Who is this content for?
      {{#if focus}}4. **{{focus}} Analysis**: Specific insights about {{focus}}{{/if}}
      
      Content:
      {{content}}
    arguments:
      content:
        description: Webpage content to summarize
        required: true
      num_points:
        description: Number of key points to extract (default 5)
        required: false
      focus:
        description: Specific aspect to focus on (e.g., technical, business, educational)
        required: false

  file-analysis:
    description: Analyze files for specific purposes
    template: |
      Analyze the following files for {{analysis_type}}:
      
      {{#if criteria}}Focus on: {{criteria}}{{/if}}
      
      {{files}}
      
      Please provide:
      - Summary of findings
      - Recommendations
      - {{#if format}}Output in {{format}} format{{/if}}
    arguments:
      files:
        description: File contents or paths to analyze
        required: true
      analysis_type:
        description: Type of analysis (security, performance, quality, etc.)
        required: true
      criteria:
        description: Specific criteria or standards to check against
        required: false
      format:
        description: Output format (markdown, JSON, report, etc.)
        required: false

Using Prompts in Claude Desktop:

Click the + icon in the message input
Select "Add from mcp-this-custom"
Choose your prompt (e.g., "summarize-webpage")
Fill in the arguments - Claude will guide you through the required and optional fields

3. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-tools": {
      "command": "uvx",
      "args": ["mcp-this", "--config-path", "/path/to/my-tools.yaml"]
    }
  }
}

4. Restart Claude Desktop

Your tools and prompts are now available! Claude can:

Fetch web content and find large files using your custom CLI tools
Use structured prompt templates for guided analysis and summarization

Configuration Format

Tool Definition

tools:
  tool-name:
    description: "Description with usage examples"
    execution:
      command: "command-template <<parameter1>> <<optional_param>>"
    parameters:
      parameter1:
        description: "Parameter description"
        required: true
      optional_param:
        description: "Optional parameter description"  
        required: false

Key Points:

Use <<parameter>> placeholders in commands
Parameters marked required: false are removed from commands if not provided
Use command: >- for multi-line commands (not command: |)

Prompt Definition

prompts:
  prompt-name:
    description: "Prompt description"
    template: |
      Template with {{argument}} placeholders.
      {{#if optional_arg}}Conditional: {{optional_arg}}{{/if}}
    arguments:
      argument:
        description: "Argument description"
        required: true
      optional_arg:
        description: "Optional argument"
        required: false

Prompts vs Tools:

Tools execute commands and use <<parameter>> syntax
Prompts generate text templates and use {{argument}} syntax with Handlebars

Configuration Methods

Method	Usage	Example
YAML File	`--config-path <path>`	`--config-path ./my-tools.yaml`
JSON String	`--config-value <json>`	`--config-value '{"tools":{...}}'`
Environment Variable	`MCP_THIS_CONFIG_PATH`	`export MCP_THIS_CONFIG_PATH=./tools.yaml`
Built-in Preset	`--preset <n>`	`--preset default`

Pre-Built Tool & Prompt Collections (Presets)

For convenience, mcp-this includes ready-to-use collections of tools and prompts:

default - Safe, read-only tools (file exploration, web scraping)
editing - File manipulation tools (create, edit, delete)
github - GitHub integration tools (PR analysis, repository operations) + specialized prompts (code-review, create-pr-description)

Quick usage:

{
  "mcpServers": {
    "mcp-this": {
      "command": "uvx", 
      "args": ["mcp-this", "--preset", "default"]
    }
  }
}

See README_PRESETS.md for complete preset documentation, tool lists, dependencies, and advanced setup.

Real-World Examples

Development Workflow Tools

tools:
  git-status-summary:
    description: Get a concise overview of git repository status
    execution:
      command: >-
        echo "=== Branch ===" && git branch --show-current &&
        echo "=== Status ===" && git status --porcelain &&
        echo "=== Recent Commits ===" && git log --oneline -5
    parameters: {}

  test-runner:
    description: Run tests with optional pattern matching
    execution:
      command: >-
        if [ -n "<<pattern>>" ]; then
          npm test -- --grep "<<pattern>>"
        else
          npm test
        fi
    parameters:
      pattern:
        description: Test pattern to match (optional)
        required: false

  docker-container-logs:
    description: Get logs from a Docker container
    execution:
      command: docker logs <<container_name>> --tail <<lines>>
    parameters:
      container_name:
        description: Name or ID of the Docker container
        required: true
      lines:
        description: Number of log lines to show (default 100)
        required: false
        default: "100"

AI-Powered Workflow Prompts

prompts:
  refactor-code:
    description: Guide code refactoring with specific goals and constraints
    template: |
      Please refactor the following code with these objectives:
      {{#if goals}}
      **Goals:**
      {{goals}}
      {{/if}}
      
      **Constraints:**
      - Maintain existing functionality
      - {{#if language}}Follow {{language}} best practices{{/if}}
      - {{#if performance}}Optimize for {{performance}}{{/if}}
      {{#if additional_constraints}}
      - {{additional_constraints}}
      {{/if}}
      
      **Code to refactor:**
      ```
      {{code}}
      ```
      
      Please provide:
      1. Refactored code with explanations
      2. Summary of changes made
      3. Potential risks or considerations
    arguments:
      code:
        description: Code to refactor
        required: true
      goals:
        description: Specific refactoring goals (e.g., improve readability, reduce complexity)
        required: false
      language:
        description: Programming language for best practices
        required: false
      performance:
        description: Performance optimization target (speed, memory, etc.)
        required: false
      additional_constraints:
        description: Any additional constraints or requirements
        required: false

  technical-documentation:
    description: Generate comprehensive technical documentation
    template: |
      Create {{doc_type}} documentation for:
      
      {{content}}
      
      **Requirements:**
      - Target audience: {{audience}}
      {{#if style}}- Documentation style: {{style}}{{/if}}
      {{#if sections}}- Include sections: {{sections}}{{/if}}
      - {{#if detail_level}}Detail level: {{detail_level}}{{/if}}
      
      {{#if examples}}**Include examples:** {{examples}}{{/if}}
      
      Please structure the documentation with clear headings, examples, and actionable information.
    arguments:
      content:
        description: Code, API, or system to document
        required: true
      doc_type:
        description: Type of documentation (API, user guide, technical spec, etc.)
        required: true
      audience:
        description: Target audience (developers, end-users, administrators, etc.)
        required: true
      style:
        description: Documentation style (formal, conversational, tutorial, reference)
        required: false
      sections:
        description: Specific sections to include
        required: false
      detail_level:
        description: Level of detail (high-level, detailed, comprehensive)
        required: false
      examples:
        description: Types of examples to include
        required: false

System Administration Tools

tools:
  port-checker:
    description: Check what process is using a specific port
    execution:
      command: lsof -i :<<port>>
    parameters:
      port:
        description: Port number to check
        required: true

  service-status:
    description: Check the status of a system service
    execution:
      command: systemctl status <<service_name>>
    parameters:
      service_name:
        description: Name of the service to check
        required: true

  disk-usage-analyzer:
    description: Analyze disk usage and find largest directories
    execution:
      command: >-
        echo "=== Disk Usage Summary ===" &&
        df -h <<path>> &&
        echo "=== Largest Directories ===" &&
        du -h <<path>> | sort -hr | head -10
    parameters:
      path:
        description: Path to analyze (default current directory)
        required: false
        default: "."

Python API Usage

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Using custom configuration
server_params = StdioServerParameters(
    command='uvx',
    args=['mcp-this', '--config-path', '/path/to/tools.yaml'],
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # List available tools
        tools = await session.list_tools()
        print([tool.name for tool in tools.tools])
        
        # Use a tool
        result = await session.call_tool(
            'git-status-summary',
            {}
        )
        print(result.content[0].text)

Installation Options

Via uvx (Recommended)

# No installation needed - uvx runs tools in isolated environments
uvx mcp-this --config-path ./my-tools.yaml

Via pip

pip install mcp-this
mcp-this --config-path ./my-tools.yaml

From Source

git clone https://github.com/your-username/mcp-this.git
cd mcp-this
uv sync
python -m mcp_this --config-path ./my-tools.yaml

Security Considerations

⚠️ Important: mcp-this executes shell commands based on your configuration. Always:

Use trusted configuration files only
Validate user inputs in production environments
Run with minimal necessary privileges
Consider containerization for additional security
Review commands for dangerous operations

See the Security section for detailed security guidance.

Development

Setup

git clone https://github.com/your-username/mcp-this.git
cd mcp-this
uv sync

Testing

make tests         # Run all tests
make unittests     # Unit tests only
make linting       # Linting only
make open_coverage # View coverage report

Building

make package-build    # Build package
make package-publish  # Publish (requires UV_PUBLISH_TOKEN)

License

Apache License 2.0