Crate clap_mcp 

clap-mcp

Expose your clap CLI as an MCP (Model Context Protocol) server over stdio.

Quick start

Prefer a single run function with #[clap_mcp_output_from = "run"] so CLI and MCP share one implementation (no duplicated logic).

use clap::Parser;
use clap_mcp::ClapMcp;

#[derive(Parser, ClapMcp)]
#[clap_mcp(reinvocation_safe, parallel_safe = false)]
#[clap_mcp_output_from = "run"]
enum Cli {
    Greet { #[arg(long)] name: Option<String> },
}

fn run(cmd: Cli) -> String {
    match cmd {
        Cli::Greet { name } => format!("Hello, {}!", name.as_deref().unwrap_or("world")),
    }
}

fn main() {
    let cli = clap_mcp::parse_or_serve_mcp_attr::<Cli>();
    println!("{}", run(cli));
}

Run with --mcp to start the MCP server instead of executing the CLI.

Modules

content

Custom MCP resources and prompts, and skill export. Custom MCP resources, prompts, and agent skills export.

Macros

clap_mcp_main

Convenience macro for struct root + subcommand CLIs: parse root then run.

output_schema_one_of

Builds a JSON schema with oneOf for the given types. Used by the derive macro when #[clap_mcp_output_one_of = "T1, T2, T3"] is set. Requires the output-schema feature and each type must implement schemars::JsonSchema.

Structs

AsStructured

Wrapper for structured (JSON) output when using #[clap_mcp_output_from]. Use when your run function returns a type that implements Serialize but is not String/&str.

ClapArg

Serializable representation of a clap argument.

ClapCommand

A command or subcommand in the schema.

ClapMcpConfig

Configuration for execution safety when exposing a CLI over MCP.

ClapMcpSchemaMetadata

Metadata for filtering and adjusting the MCP schema.

ClapMcpServeOptions

Optional configuration for MCP serve behavior (logging, etc.).

ClapMcpToolError

Error produced when a tool’s run function returns Err(e) (e.g. Result<O, E>).

ClapSchema

Serializable schema extracted from a clap Command. Used to build MCP tools and invoke the CLI.

Enums

ClapMcpError

Errors that can occur when running the MCP server.

ClapMcpToolOutput

Output produced by a CLI command for MCP tool results.

Constants

EXPORT_SKILLS_FLAG_LONG

Long flag that triggers Agent Skills export (generates SKILL.md). Add via command_with_export_skills_flag.

LOGGING_GUIDE_CONTENT

Full content for the logging guide prompt (returned when clients request PROMPT_LOGGING_GUIDE).

LOG_INTERPRETATION_INSTRUCTIONS

Log interpretation hint for MCP clients (included in instructions when logging is enabled).

MCP_FLAG_LONG

Long flag that triggers MCP server mode. Add to your CLI via command_with_mcp_flag.

MCP_RESOURCE_URI_SCHEMA

URI for the clap schema resource exposed by the MCP server.

PROMPT_LOGGING_GUIDE

Name of the logging guide prompt.

Traits

ClapMcpConfigProvider

Provides MCP execution safety configuration from #[clap_mcp(...)] attributes. Implemented by the #[derive(ClapMcp)] macro.

ClapMcpRunnable

Produces the output string for a parsed CLI value. Used for in-process MCP tool execution when reinvocation_safe is true. Implemented by the #[derive(ClapMcp)] macro via the blanket impl for ClapMcpToolExecutor.

ClapMcpSchemaMetadataProvider

Provides MCP schema metadata (skip, requires) from #[clap_mcp(skip)] and #[clap_mcp(requires = "arg_name")] attributes.

ClapMcpToolExecutor

Produces MCP tool output (text or structured) for a parsed CLI value.

IntoClapMcpResult

Converts the return value of a run function (used with #[clap_mcp_output_from]) into MCP tool output or error.

IntoClapMcpToolError

Converts an error type from a run function into ClapMcpToolError. Used when run returns Result<O, E> and the Err branch is taken.

ParseOrServeMcp

Canonical entrypoint for derive-based CLIs: parse (or serve if --mcp) and return self.

Functions

command_with_export_skills_flag

Adds a root-level --export-skills flag (optional value for output directory) to a clap::Command.

command_with_mcp_and_export_skills_flags

Adds both --mcp and --export-skills flags to the command. Use this so schema extraction omits both; check for export-skills before mcp in the parse flow.

command_with_mcp_flag

Adds a root-level --mcp flag to a clap::Command (imperative clap usage).

get_matches_or_serve_mcp

Imperative clap entrypoint.

get_matches_or_serve_mcp_with_config

Imperative clap entrypoint with execution safety configuration.

get_matches_or_serve_mcp_with_config_and_metadata

Imperative clap entrypoint with execution safety configuration and schema metadata.

output_schema_for_type

parse_or_serve_mcp

High-level helper for clap derive-based CLIs.

parse_or_serve_mcp_attr

High-level helper for clap derive-based CLIs with config from #[clap_mcp(...)] attributes.

parse_or_serve_mcp_with_config

High-level helper for clap derive-based CLIs with execution safety configuration.

parse_or_serve_mcp_with_config_and_options

Like parse_or_serve_mcp_with_config but with custom serve options (e.g. logging).

run_async_tool

Runs an async future for MCP tool execution, respecting share_runtime in config.

run_or_serve_mcp

Run parsed CLI through a closure, or serve MCP if --mcp is present.

schema_from_command

Extracts a serializable schema from a clap::Command (imperative clap usage).

schema_from_command_with_metadata

Extracts a schema from a clap::Command with MCP metadata applied.

serve_schema_json_over_stdio

Starts an MCP server over stdio exposing clap://schema with the provided JSON payload.

serve_schema_json_over_stdio_blocking

Convenience wrapper for serve_schema_json_over_stdio that blocks on a tokio runtime.

tools_from_schema

Builds MCP tools from a clap schema.

tools_from_schema_with_config

Builds MCP tools from a clap schema with execution safety annotations.

tools_from_schema_with_config_and_metadata

Builds MCP tools from a clap schema with config and optional metadata. When metadata.output_schema is set, each tool’s output_schema field is set to that value. When metadata.skip_root_command_when_subcommands is true and the root has subcommands, the root command is excluded from the tool list (only subcommands become tools).

Type Aliases

InProcessToolHandler

Type for in-process tool execution handler.

Derive Macros

ClapMcp

Derive macro for ClapMcpConfigProvider and ClapMcpToolExecutor.