Click MCP

🚀 Click-mcp English Documentation

click-mcp is a Python library that extends Click applications to support the Model Context Protocol (MCP), enabling AI agents to interact with CLI tools.

🚀 Quick Start

click-mcp is a Python library that extends Click applications to support the Model Context Protocol (MCP), allowing AI agents to interact with CLI tools.

✨ Features

• Simple @click_mcp decorator syntax.
• Automatically convert Click commands into MCP tools.
• Support for nested command groups.
• Support for MCP servers based on standard input and output (stdio).

📦 Installation

pip install click-mcp

💻 Usage Examples

Basic Usage

import click
from click_mcp import click_mcp

@click_mcp(server_name="my-cli-app")
@click.group()
def cli():
    """Example CLI application."""
    pass

@cli.command()
@click.option('--name', required=True, help='The name to greet')
def greet(name):
    """Greet someone."""
    click.echo(f"Hello, {name}!")

if __name__ == '__main__':
    cli()

When running the MCP server, Click commands are converted into MCP tools:

python3 your_script.py serve

The output will be:

MCP Server starting on port 8080...

Advanced Usage

Customize Command and Server Names

You can customize the names of the MCP server and commands through the server_name and command_name parameters:

@click_mcp(server_name="my-custom-server", command_name="my-command")
def my_command():
    pass

Nested Command Groups

click-mcp supports nested command groups, allowing you to create sub - commands for different functions.

📚 Documentation

Error Handling

If an error occurs during runtime, click-mcp will automatically catch the exception and return it in JSON format:

{
    "error": {
        "type": "ValueError",
        "message": "invalid value"
    }
}

Development

Set up the Environment

1. Clone the repository:

   git clone https://github.com/yourusername/click-mcp.git
   cd click-mcp
   

2. Install dependencies:

   pip install hatch
   

Run Tests

# Run all tests
hatch run test

# Tests with coverage
hatch run cov

Format Code

# Format code
hatch run format

# Check format
hatch run check-format

Code Inspection

hatch run lint

Type Checking

hatch run typecheck

Run All Checks

hatch run check-all

Build

hatch run build

Generate Documentation

hatch run docs

Related Resources

• Model Context Protocol (MCP) Specification
• Click Documentation
• MCP Tool Registry

📄 License

MIT