What is Clap Mcp

clap-mcp is a Rust library that allows any Clap command-line interface (CLI) to function as a Multi-Client Protocol (MCP) server using a simple derive macro. This enables developers to easily build applications that can be interacted with both through the command line and as server applications for client connections.

Use cases

clap-mcp can be used to turn existing CLI applications into MCP servers, which can handle commands from various clients. This is particularly useful for applications that require remote command execution, like calculators, build tools, or other utilities that benefit from both command-line usage and network access.

How to use

To use clap-mcp, add it as a dependency in your Cargo.toml file. Define your CLI struct with the #[derive(Parser, McpMode)] macro. Implement your commands as subcommands and handle them through a central execution function. You can configure the application to run in CLI mode or MCP server mode using flags, including options for HTTP server ports.

Key features

Key features of clap-mcp include the automatic exposure of all commands as MCP tools, mapping of CLI arguments to tool parameters, preservation of existing CLI functionalities, and support for both standard input/output and HTTP server modes. This simplifies the process of enabling command execution over a network.

Where to use

clap-mcp is suitable for use in Rust applications that need to operate as both command-line tools and networked server applications. It is ideal for scenarios where remote command execution, automated scripting, or client-server interactions are required, such as in build systems, APIs, or multi-user applications.

clap-mcp

Turn any Clap CLI into an MCP server with a simple derive macro.

Installation

[dependencies]
clap-mcp = "0.1"

Quick Start

Here’s a complete calculator example that works as both a CLI and MCP server:

use clap::{Parser, Subcommand};
use clap_mcp::McpMode;

#[derive(Parser, McpMode)]
#[command(name = "calculator")]
#[command(about = "A simple calculator CLI that can also run as an MCP server")]
struct Cli {
    #[command(subcommand)]
    command: Option<Commands>,
    
    /// Run as MCP server instead of CLI
    #[arg(long)]
    #[mcp(mode_flag)]
    mcp: bool,
    
    /// Port to run MCP HTTP server on (if not specified, uses stdio)
    #[arg(long, value_name = "PORT")]
    mcp_port: Option<u16>,
}

#[derive(Subcommand, Clone)]
enum Commands {
    /// Add two numbers
    Add {
        #[arg(short, long)]
        a: f64,
        #[arg(short, long)]
        b: f64,
    },
    
    /// Multiply two numbers
    Multiply {
        #[arg(long)]
        value1: f64,
        #[arg(long)]
        value2: f64,
    },
}

fn execute_command(cmd: Commands) -> Result<String, String> {
    match cmd {
        Commands::Add { a, b } => {
            Ok(format!("{} + {} = {}", a, b, a + b))
        }
        Commands::Multiply { value1, value2 } => {
            Ok(format!("{} * {} = {}", value1, value2, value1 * value2))
        }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cli = Cli::parse();
    
    if cli.mcp {
        // Run as MCP server - automatically exposes all commands as tools
        if let Some(port) = cli.mcp_port {
            // HTTP server mode on specified port
            let addr = format!("127.0.0.1:{}", port).parse()?;
            cli.run_mcp_server_http_with_handler(addr, execute_command)?;
        } else {
            // stdio mode (default)
            cli.run_mcp_server_with_handler(execute_command)?;
        }
    } else {
        // Run as normal CLI
        match execute_command(cli.command.expect("Subcommand required")) {
            Ok(output) => println!("{}", output),
            Err(e) => eprintln!("Error: {}", e),
        }
    }
    
    Ok(())
}

Now your CLI works both ways:

# Traditional CLI mode
$ calculator add -a 10 -b 32
10 + 32 = 42

$ calculator multiply --value1 7 --value2 6
7 * 6 = 42

# MCP server mode (stdio)
$ calculator --mcp
# Server is now running, ready for MCP clients to connect

# MCP server mode (HTTP on specific port)
$ calculator --mcp --mcp-port 8080
# Server running on http://127.0.0.1:8080, ready for HTTP-based MCP clients

Real Example: Cast

Here’s how you’d make Cast (Foundry’s CLI) work as an MCP server:

#[derive(Parser, McpMode)]
struct Cast {
    #[command(subcommand)]
    cmd: CastCommand,
    
    #[arg(long)]
    #[mcp(mode_flag)]
    mcp: bool,
}

// That's it. All Cast commands are now available as MCP tools.

How It Works

The #[derive(McpMode)] macro:

• Adds a run_mcp_server() method to your CLI
• Converts each subcommand into an MCP tool
• Maps CLI arguments to tool parameters with proper types
• Preserves all existing CLI functionality

License

MIT OR Apache-2.0