fastmcp.cli.cli

FastMCP CLI tools using Cyclopts.

Functions

with_argv ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

with_argv(args: list[str] | None)

Temporarily replace sys.argv if args provided.

This context manager is used at the CLI boundary to inject server arguments when needed, without mutating sys.argv deep in the source loading logic.

Args are provided without the script name, so we preserve sys.argv[0] and replace the rest.

version ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L96" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

version()

Display version information and platform details.

inspector ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L142" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

inspector(server_spec: str | None = None) -> None

Run an MCP server with the MCP Inspector for development.

Args:

• server_spec: Python file to run, optionally with :object suffix, or None to auto-detect fastmcp.json

apps ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L337" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

apps(server_spec: str) -> None

Preview a FastMCPApp UI in the browser.

Starts the MCP server from SERVER_SPEC on --mcp-port, launches a local dev UI on --dev-port with a tool picker and AppBridge host, then opens the browser automatically.

Requires fastmcp[apps] to be installed (prefab-ui).

run ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L385" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

run(server_spec: str | None = None, *server_args: str) -> None

Run an MCP server or connect to a remote one.

The server can be specified in several ways:

1. Module approach: "server.py" - runs the module directly, looking for an object named 'mcp', 'server', or 'app'
2. Import approach: "server.py:app" - imports and runs the specified server object
3. URL approach: "http://server-url" - connects to a remote server and creates a proxy
4. MCPConfig file: "mcp.json" - runs as a proxy server for the MCP Servers in the MCPConfig file
5. FastMCP config: "fastmcp.json" - runs server using FastMCP configuration
6. No argument: looks for fastmcp.json in current directory
7. Module mode: "-m my_module" - runs the module directly via python -m

Server arguments can be passed after -- : fastmcp run server.py -- --config config.json --debug

Args:

• server_spec: Python file, object specification (file:obj), config file, URL, or None to auto-detect

inspect ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L764" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

inspect(server_spec: str | None = None) -> None

Inspect an MCP server and display information or generate a JSON report.

This command analyzes an MCP server. Without flags, it displays a text summary. Use --format to output complete JSON data.

Examples:

Show text summary

fastmcp inspect server.py

Output FastMCP format JSON to stdout

fastmcp inspect server.py --format fastmcp

Save MCP protocol format to file (format required with -o)

fastmcp inspect server.py --format mcp -o manifest.json

Inspect from fastmcp.json configuration

fastmcp inspect fastmcp.json fastmcp inspect # auto-detect fastmcp.json

Args:

• server_spec: Python file to inspect, optionally with :object suffix, or fastmcp.json

prepare ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/cli/cli.py#L1006" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

prepare(config_path: Annotated[str | None, cyclopts.Parameter(help='Path to fastmcp.json configuration file')] = None, output_dir: Annotated[str | None, cyclopts.Parameter(help='Directory to create the persistent environment in')] = None, skip_source: Annotated[bool, cyclopts.Parameter(help='Skip source preparation (e.g., git clone)')] = False) -> None

Prepare a FastMCP project by creating a persistent uv environment.

This command creates a persistent uv project with all dependencies installed:

• Creates a pyproject.toml with dependencies from the config
• Installs all Python packages into a .venv
• Prepares the source (git clone, download, etc.) unless --skip-source

After running this command, you can use: fastmcp run <config> --project <output-dir>

This is useful for:

• CI/CD pipelines with separate build and run stages
• Docker images where you prepare during build
• Production deployments where you want fast startup times