Generate CLI - Fastmcp

import { VersionBadge } from '/snippets/version-badge.mdx'

fastmcp list and fastmcp call are general-purpose — you always specify the server, the tool name, and the arguments from scratch. fastmcp generate-cli goes further: it connects to a server, reads its tool schemas, and writes a standalone Python script where every tool is a proper subcommand with typed flags, help text, and tab completion. The result is a CLI that feels hand-written for that specific server.

MCP tool schemas already contain everything a CLI framework needs — parameter names, types, descriptions, required/optional status, and defaults. generate-cli maps that into cyclopts commands, so JSON Schema types become Python type annotations, descriptions become --help text, and required parameters become mandatory flags.

Generating a Script

Point the command at any server target and it writes a CLI script:

bash

fastmcp generate-cli weather
fastmcp generate-cli http://localhost:8000/mcp
fastmcp generate-cli server.py my_weather_cli.py

The second positional argument sets the output path (defaults to cli.py). If the file already exists, pass -f to overwrite:

bash

fastmcp generate-cli weather -f

What You Get

The generated script is a regular Python file — executable, editable, and yours:

$ python cli.py call-tool --help
Usage: weather-cli call-tool COMMAND

Call a tool on the server

Commands:
  get_forecast  Get the weather forecast for a city.
  search_city   Search for a city by name.

Each tool has typed parameters with help text pulled directly from the server's schema:

$ python cli.py call-tool get_forecast --help
Usage: weather-cli call-tool get_forecast [OPTIONS]

Get the weather forecast for a city.

Options:
  --city    [str]  City name (required)
  --days    [int]  Number of forecast days (default: 3)

Beyond tool commands, the script includes generic MCP operations — list-tools, list-resources, read-resource, list-prompts, and get-prompt — that always reflect the server's current state, even if tools have changed since generation.

Parameter Handling

Parameters are mapped based on their JSON Schema type:

Simple types (string, integer, number, boolean) become typed flags:

bash

python cli.py call-tool get_forecast --city London --days 3

Arrays of simple types become repeatable flags:

bash

python cli.py call-tool tag_items --tags python --tags fastapi --tags mcp

Complex types (objects, nested arrays, unions) accept JSON strings. The --help output shows the full schema so you know what structure to pass:

bash

python cli.py call-tool create_user \
  --name John \
  --metadata '{"role": "admin", "dept": "engineering"}'

Agent Skill

Alongside the CLI script, generate-cli writes a SKILL.md file — a Claude Code agent skill that documents every tool's exact invocation syntax, parameter flags, types, and descriptions. An agent can pick up the CLI immediately without running --help or experimenting with flag names.

To skip skill generation:

bash

fastmcp generate-cli weather --no-skill

How It Works

The generated script is a client, not a server — it connects to the server on every invocation rather than bundling it. A CLIENT_SPEC variable at the top holds the resolved transport (a URL string or StdioTransport with baked-in command and arguments).

The most common edit is changing CLIENT_SPEC — for example, pointing a script generated from a dev server at production. Beyond that, the helper functions (_call_tool, _print_tool_result) are thin wrappers around fastmcp.Client that are easy to adapt.

The script requires fastmcp as a dependency. If it lives outside a project that already has FastMCP installed:

bash

uv run --with fastmcp python cli.py call-tool get_forecast --city London