mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-28 10:18:08 +02:00
Add fastmcp list and fastmcp call CLI commands (#3054)
This commit is contained in:
Jeremiah Lowin
GitHub
parent
684cbff634
commit
bd37763e98
9 changed files with 1862 additions and 0 deletions
126
docs/clients/cli.mdx
Normal file
126
docs/clients/cli.mdx
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
---
|
||||
title: Client CLI
|
||||
sidebarTitle: CLI
|
||||
description: Query and invoke MCP server tools directly from the terminal with fastmcp list and fastmcp call.
|
||||
icon: terminal
|
||||
---
|
||||
|
||||
import { VersionBadge } from '/snippets/version-badge.mdx'
|
||||
|
||||
<VersionBadge version="3.0.0" />
|
||||
|
||||
MCP servers are designed for programmatic consumption by AI assistants and applications. But during development, you often want to poke at a server directly: check what tools it exposes, call one with test arguments, or verify that a deployment is responding correctly. The FastMCP CLI gives you that direct access with two commands, `fastmcp list` and `fastmcp call`, so you can query and invoke any MCP server without writing a single line of Python.
|
||||
|
||||
These commands are also valuable for LLM-based agents that lack native MCP support. An agent that can execute shell commands can use `fastmcp list --json` to discover available tools and `fastmcp call --json` to invoke them, with structured JSON output designed for programmatic consumption.
|
||||
|
||||
## Server Targets
|
||||
|
||||
Both commands need to know which server to talk to. You provide a "server spec" as the first argument, and FastMCP figures out the transport automatically. You can point at an HTTP URL for a running server, a Python file that defines one, a JSON configuration file that describes one, or a JavaScript file. The CLI resolves the right connection mechanism so you can focus on the query.
|
||||
|
||||
```bash
|
||||
fastmcp list http://localhost:8000/mcp
|
||||
fastmcp list server.py
|
||||
fastmcp list mcp-config.json
|
||||
```
|
||||
|
||||
Python files are handled with particular care. Rather than requiring your script to call `mcp.run()` at the bottom, the CLI routes it through `fastmcp run` internally, which means any Python file that defines a FastMCP server object works as a target with no boilerplate.
|
||||
|
||||
For servers that communicate over stdio (common with Node.js-based MCP servers), use the `--command` flag instead of a positional server spec. The string is shell-split into a command and arguments.
|
||||
|
||||
```bash
|
||||
fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
|
||||
```
|
||||
|
||||
## Discovering Tools
|
||||
|
||||
`fastmcp list` connects to a server and prints every tool it exposes. The default output is compact: each tool appears as a function signature with its parameter names, types, and a description.
|
||||
|
||||
```bash
|
||||
fastmcp list http://localhost:8000/mcp
|
||||
```
|
||||
|
||||
The output looks like a Python function signature, making it easy to see at a glance what a tool expects and what it returns. Required parameters appear with just their type annotation, while optional ones show their defaults.
|
||||
|
||||
When you need the full JSON Schema for a tool's inputs or outputs -- useful for understanding nested object structures or enum constraints -- opt into them with `--input-schema` or `--output-schema`. These print the raw schema beneath each tool signature.
|
||||
|
||||
### Beyond Tools
|
||||
|
||||
MCP servers can expose resources and prompts alongside tools. By default, `fastmcp list` only shows tools because they are the most common interaction point. Add `--resources` or `--prompts` to include those in the output.
|
||||
|
||||
```bash
|
||||
fastmcp list server.py --resources --prompts
|
||||
```
|
||||
|
||||
Resources appear with their URIs and descriptions. Prompts appear with their argument names so you can see what parameters they accept.
|
||||
|
||||
### Machine-Readable Output
|
||||
|
||||
The `--json` flag switches from human-friendly text to structured JSON. Each tool includes its name, description, and full input schema (and output schema when present). When combined with `--resources` or `--prompts`, those are included as additional top-level keys.
|
||||
|
||||
```bash
|
||||
fastmcp list server.py --json
|
||||
```
|
||||
|
||||
This is the format to use when building automation around MCP servers or feeding tool definitions to an LLM agent that needs to decide which tool to call.
|
||||
|
||||
## Calling Tools
|
||||
|
||||
`fastmcp call` invokes a single tool on a server. You provide the server spec, the tool name, and arguments as `key=value` pairs. The CLI fetches the tool's schema, coerces your string values to the correct types (integers, floats, booleans, arrays, objects), and makes the call.
|
||||
|
||||
```bash
|
||||
fastmcp call http://localhost:8000/mcp search query=hello limit=5
|
||||
```
|
||||
|
||||
Type coercion is driven by the tool's JSON Schema. If a parameter is declared as an integer, the string `"5"` becomes the integer `5`. Booleans accept `true`/`false`, `yes`/`no`, and `1`/`0`. Array and object parameters are parsed as JSON.
|
||||
|
||||
For tools with complex or deeply nested arguments, the `key=value` syntax gets unwieldy. You can pass a single JSON object as the argument instead, and the CLI treats it as the full input dictionary.
|
||||
|
||||
```bash
|
||||
fastmcp call server.py create_item '{"name": "Widget", "tags": ["sale", "new"], "metadata": {"color": "blue"}}'
|
||||
```
|
||||
|
||||
Alternatively, `--input-json` provides the base argument dictionary. Any `key=value` pairs you add alongside it override keys from the JSON, which is useful for templating a complex call and varying one parameter at a time.
|
||||
|
||||
### Error Handling
|
||||
|
||||
The CLI validates your call before sending it. If you misspell a tool name, it uses fuzzy matching to suggest corrections. If you omit a required argument, it tells you which ones are missing and prints the tool's signature as a reminder.
|
||||
|
||||
When a tool call itself returns an error (the server executed the tool but it failed), the error message is printed and the CLI exits with a non-zero status code, making it straightforward to use in scripts.
|
||||
|
||||
### Structured Output
|
||||
|
||||
Like `fastmcp list`, the `--json` flag on `fastmcp call` emits structured JSON instead of formatted text. The output includes the content blocks, error status, and structured content when the server provides it. Use this when you need to parse tool results programmatically.
|
||||
|
||||
```bash
|
||||
fastmcp call server.py get_weather city=London --json
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
When the server target is an HTTP URL, the CLI automatically enables OAuth authentication. If the server requires it, you will be guided through the OAuth flow (typically opening a browser for authorization). If the server has no auth requirements, the OAuth setup is a silent no-op.
|
||||
|
||||
To explicitly disable authentication -- for example, when connecting to a local development server where OAuth setup would just slow you down -- pass `--auth none`.
|
||||
|
||||
```bash
|
||||
fastmcp call http://localhost:8000/mcp my_tool --auth none
|
||||
```
|
||||
|
||||
## Transport Override
|
||||
|
||||
FastMCP defaults to Streamable HTTP for URL targets. If you are connecting to a server that only supports Server-Sent Events (SSE), use `--transport sse` to force the older transport. This appends `/sse` to the URL path automatically so the client picks the correct protocol.
|
||||
|
||||
```bash
|
||||
fastmcp list http://localhost:8000 --transport sse
|
||||
```
|
||||
|
||||
## Interactive Elicitation
|
||||
|
||||
Some MCP tools request additional input from the user during execution through a mechanism called elicitation. When a tool sends an elicitation request, the CLI prints the server's question to the terminal and prompts you to respond. Each field in the elicitation schema is presented with its name and expected type, and required fields are clearly marked.
|
||||
|
||||
You can type `decline` to skip a question or `cancel` to abort the tool call entirely. This interactive behavior means the CLI works naturally with tools that have multi-step or conversational workflows.
|
||||
|
||||
## LLM Agent Integration
|
||||
|
||||
For LLM agents that can execute shell commands but lack built-in MCP support, the CLI provides a clean integration path. The agent calls `fastmcp list --json` to get a structured description of every available tool, including full input schemas, and then calls `fastmcp call --json` with the chosen tool and arguments. Both commands return well-formed JSON that is straightforward to parse.
|
||||
|
||||
Because the CLI handles connection management, transport selection, and type coercion internally, the agent does not need to understand MCP protocol details. It just needs to read JSON and construct shell commands.
|
||||
|
|
@ -6,6 +6,33 @@ This document tracks major features in FastMCP v3.0 for release notes preparatio
|
|||
|
||||
## 3.0.0beta2
|
||||
|
||||
### CLI: `fastmcp list` and `fastmcp call`
|
||||
|
||||
New client-side CLI commands for querying and invoking tools on any MCP server — remote URLs, local Python files, MCPConfig JSON, or arbitrary stdio commands. Especially useful for giving LLMs that don't have built-in MCP support access to MCP tools via shell commands.
|
||||
|
||||
```bash
|
||||
# Discover tools on a server
|
||||
fastmcp list http://localhost:8000/mcp
|
||||
fastmcp list server.py
|
||||
fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
|
||||
|
||||
# Call a tool
|
||||
fastmcp call server.py greet name=World
|
||||
fastmcp call http://localhost:8000/mcp search query=hello limit=5
|
||||
fastmcp call server.py create_item '{"name": "Widget", "tags": ["a", "b"]}'
|
||||
```
|
||||
|
||||
Key features:
|
||||
- Tool arguments are auto-coerced using the tool's JSON schema (`limit=5` → int)
|
||||
- Single JSON objects work as positional args alongside `key=value` and `--input-json`
|
||||
- `--input-schema` / `--output-schema` for full JSON schemas, `--json` for machine-readable output
|
||||
- `--transport sse` for SSE servers, `--command` for stdio servers
|
||||
- Auto OAuth for HTTP targets (no-ops if server doesn't require auth)
|
||||
- Fuzzy tool name matching suggests alternatives on typos
|
||||
- Interactive terminal elicitation for tools that request user input mid-execution
|
||||
|
||||
Documentation: [Client CLI](/clients/cli)
|
||||
|
||||
### CLI: Expanded Reload File Watching
|
||||
|
||||
The `--reload` flag now watches a comprehensive set of file types, making it suitable for MCP apps with frontend bundles ([#3028](https://github.com/jlowin/fastmcp/pull/3028)). Previously limited to `.py` files, it now watches JavaScript, TypeScript, HTML, CSS, config files, and media assets.
|
||||
|
|
|
|||
|
|
@ -168,6 +168,7 @@
|
|||
"group": "Clients",
|
||||
"pages": [
|
||||
"clients/client",
|
||||
"clients/cli",
|
||||
"clients/transports",
|
||||
{
|
||||
"group": "Core Operations",
|
||||
|
|
|
|||
|
|
@ -18,6 +18,8 @@ fastmcp --help
|
|||
|
||||
| Command | Purpose | Dependency Management |
|
||||
| ------- | ------- | --------------------- |
|
||||
| `list` | List tools on any MCP server | **Supports:** URLs, local files, MCPConfig JSON, stdio commands. **Deps:** N/A (connects to existing servers) |
|
||||
| `call` | Call a tool on any MCP server | **Supports:** URLs, local files, MCPConfig JSON, stdio commands. **Deps:** N/A (connects to existing servers) |
|
||||
| `run` | Run a FastMCP server directly | **Supports:** Local files, factory functions, URLs, fastmcp.json configs, MCP configs. **Deps:** Uses your local environment directly. With `--python`, `--with`, `--project`, or `--with-requirements`: Runs via `uv run` subprocess. With fastmcp.json: Automatically manages dependencies based on configuration |
|
||||
| `dev` | Run a server with the MCP Inspector for testing | **Supports:** Local files and fastmcp.json configs. **Deps:** Always runs via `uv run` subprocess (never uses your local environment); dependencies must be specified or available in a uv-managed project. With fastmcp.json: Uses configured dependencies |
|
||||
| `install` | Install a server in MCP client applications | **Supports:** Local files and fastmcp.json configs. **Deps:** Creates an isolated environment; dependencies must be explicitly specified with `--with` and/or `--with-editable`. With fastmcp.json: Uses configured dependencies |
|
||||
|
|
@ -25,6 +27,138 @@ fastmcp --help
|
|||
| `project prepare` | Create a persistent uv project from fastmcp.json environment config | **Supports:** fastmcp.json configs only. **Deps:** Creates a uv project directory with all dependencies pre-installed for reuse with `--project` flag |
|
||||
| `version` | Display version information | N/A |
|
||||
|
||||
## `fastmcp list`
|
||||
|
||||
List tools available on any MCP server. This works with remote URLs, local Python files, MCPConfig JSON files, and arbitrary stdio commands. Together with `fastmcp call`, these commands are especially useful for giving LLMs that don't have built-in MCP support access to MCP tools via shell commands.
|
||||
|
||||
```bash
|
||||
fastmcp list http://localhost:8000/mcp
|
||||
fastmcp list server.py
|
||||
fastmcp list mcp.json
|
||||
fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
|
||||
```
|
||||
|
||||
By default, the output shows each tool's signature and description. Use `--input-schema` or `--output-schema` to include full JSON schemas, or `--json` for machine-readable output.
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Flag | Description |
|
||||
| ------ | ---- | ----------- |
|
||||
| Command | `--command` | Connect to a stdio server command (e.g. `'npx -y @mcp/server'`) |
|
||||
| Transport | `--transport`, `-t` | Force transport type for URL targets (`http` or `sse`) |
|
||||
| Resources | `--resources` | Also list resources |
|
||||
| Prompts | `--prompts` | Also list prompts |
|
||||
| Input Schema | `--input-schema` | Show full input schemas |
|
||||
| Output Schema | `--output-schema` | Show full output schemas |
|
||||
| JSON | `--json` | Output as JSON |
|
||||
| Timeout | `--timeout` | Connection timeout in seconds |
|
||||
| Auth | `--auth` | Auth method: `oauth` (default for HTTP), a bearer token, or `none` to disable |
|
||||
|
||||
### Server Targets
|
||||
|
||||
The `<server>` argument accepts:
|
||||
|
||||
1. **URLs** — `http://` or `https://` endpoints. Uses Streamable HTTP by default; pass `--transport sse` for SSE servers.
|
||||
2. **Python files** — `.py` files are run via `fastmcp run` automatically.
|
||||
3. **MCPConfig JSON** — `.json` files with an `mcpServers` key are treated as multi-server configs.
|
||||
4. **Stdio commands** — Use `--command` to connect to any MCP server via stdio (e.g. `npx`, `uvx`).
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# List tools on a remote server
|
||||
fastmcp list http://localhost:8000/mcp
|
||||
|
||||
# List tools from a local Python file
|
||||
fastmcp list server.py
|
||||
|
||||
# Include full input schemas
|
||||
fastmcp list server.py --input-schema
|
||||
|
||||
# Machine-readable JSON
|
||||
fastmcp list server.py --json
|
||||
|
||||
# SSE server
|
||||
fastmcp list http://localhost:8000/mcp --transport sse
|
||||
|
||||
# Stdio command
|
||||
fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
|
||||
|
||||
# Include resources and prompts
|
||||
fastmcp list server.py --resources --prompts
|
||||
```
|
||||
|
||||
## `fastmcp call`
|
||||
|
||||
Call a tool on any MCP server. Arguments can be passed as `key=value` pairs, a single JSON object, or via `--input-json`.
|
||||
|
||||
```bash
|
||||
fastmcp call server.py greet name=World
|
||||
fastmcp call http://localhost:8000/mcp search query=hello limit=5
|
||||
fastmcp call server.py create_item '{"name": "x", "tags": ["a", "b"]}'
|
||||
```
|
||||
|
||||
Tool arguments are automatically coerced to the correct type based on the tool's input schema — string values like `limit=5` become integers when the schema expects one.
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Flag | Description |
|
||||
| ------ | ---- | ----------- |
|
||||
| Command | `--command` | Connect to a stdio server command (e.g. `'npx -y @mcp/server'`) |
|
||||
| Transport | `--transport`, `-t` | Force transport type for URL targets (`http` or `sse`) |
|
||||
| Input JSON | `--input-json` | JSON string of tool arguments (merged with key=value args) |
|
||||
| JSON | `--json` | Output raw JSON result |
|
||||
| Timeout | `--timeout` | Connection timeout in seconds |
|
||||
| Auth | `--auth` | Auth method: `oauth` (default for HTTP), a bearer token, or `none` to disable |
|
||||
|
||||
### Argument Passing
|
||||
|
||||
There are three ways to pass arguments:
|
||||
|
||||
**Key=value pairs** are the simplest for flat arguments. Values are coerced using the tool's JSON schema (strings become ints, bools, etc.):
|
||||
|
||||
```bash
|
||||
fastmcp call server.py search query=hello limit=5 verbose=true
|
||||
```
|
||||
|
||||
**A single JSON object** works when you have structured or nested arguments:
|
||||
|
||||
```bash
|
||||
fastmcp call server.py create_item '{"name": "Widget", "tags": ["new", "sale"]}'
|
||||
```
|
||||
|
||||
**`--input-json`** provides a base dict that key=value pairs can override:
|
||||
|
||||
```bash
|
||||
fastmcp call server.py search --input-json '{"query": "hello", "limit": 5}' limit=10
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Call a tool with simple args
|
||||
fastmcp call server.py greet name=World
|
||||
|
||||
# Call with JSON object
|
||||
fastmcp call server.py create '{"name": "x", "tags": ["a"]}'
|
||||
|
||||
# Get JSON output for scripting
|
||||
fastmcp call server.py add a=3 b=4 --json
|
||||
|
||||
# Call a tool on a remote server
|
||||
fastmcp call http://localhost:8000/mcp search query=hello
|
||||
|
||||
# Call via stdio command
|
||||
fastmcp call --command 'npx -y @mcp/server' tool_name arg=value
|
||||
|
||||
# Disable OAuth for HTTP targets
|
||||
fastmcp call http://localhost:8000/mcp search query=hello --auth none
|
||||
```
|
||||
|
||||
<Tip>
|
||||
If you call a tool that doesn't exist, FastMCP will suggest similar tool names. Use `fastmcp list` to see all available tools on a server.
|
||||
</Tip>
|
||||
|
||||
## `fastmcp run`
|
||||
|
||||
Run a FastMCP server directly or proxy a remote server.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue