FastMCP 客户端 CLI 实战指南用 fastmcp list / call / discover 查询与调用任意 MCP 服务器【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcpFastMCP 客户端 CLI 提供了一组与服务器实现完全解耦的命令行工具fastmcp list用于发现并列出任意 MCP 服务器HTTP 远程服务器、本地 Python 文件、MCPConfig JSON、stdio 进程暴露的工具、资源和提示词fastmcp call用于以keyvalue或 JSON 参数直接调用工具、读取资源、渲染提示词fastmcp discover则扫描编辑器与项目配置让服务器可以通过名字被引用。本文以仓库中的 skills/fastmcp-client-cli/SKILL.md 为骨架结合 CLI 客户端源码 与 服务器发现源码完整讲解这些命令的用法、参数、服务器定位机制、参数类型自动转换、OAuth 认证行为以及推荐的工作流适合需要在脚本、CI 或 LLM Agent 中集成 MCP 工具的开发者。一、快速上手从列出工具到调用工具SKILL.md 给出的核心心智模型是先list发现再call调用。两条命令共享同一套服务器定位语法因此学会了定位服务器两条命令就都会用了。# 1. 查看本机已配置了哪些 MCP 服务器 fastmcp discover # 2. 查看某个服务器暴露了哪些工具 fastmcp list weather # 3. 调用其中的工具 fastmcp call weather get_forecast cityLondon调用一个不存在的工具时CLI 会基于工具名做近似匹配并给出建议实现于 client.py 中的difflib.get_close_matches最多推荐 3 个、相似度阈值 0.5例如提示Did you mean: get_forecast?。二、fastmcp list列出服务器能力fastmcp list连接服务器并打印其工具签名参数名、类型、描述一目了然是快速了解这台服务器能做什么的入口。其核心实现是 list_command解析服务器目标 → 建立 Client →client.list_tools()可选地再拉取资源与提示词。2.1 针对不同类型服务器目标的用法# 远程 HTTP/HTTPS 服务器 fastmcp list http://localhost:8000/mcp # 本地 Python 文件自动通过 fastmcp run 启动 fastmcp list server.py # 包含多个服务器的 MCPConfig JSON fastmcp list mcp.json # stdio 命令npx、uvx 等 fastmcp list --command npx -y modelcontextprotocol/server-github其中 Python 文件目标值得特别说明源码 resolve_server_spec 会把.py文件解析为StdioTransport(commandfastmcp, args[run, 文件路径, --no-banner])也就是说fastmcp list server.py实际上是通过fastmcp run在本机拉起该脚本再通过 stdio 连接因此脚本本身不需要调用mcp.run()。仓库中如 examples/echo.py、examples/get_file.py 这类用FastMCP()声明工具、资源、提示词的示例都可以直接作为fastmcp list的目标。2.2 输出控制参数参数作用源码位置--input-schema同时打印每个工具的完整输入 JSON Schemalist_command 参数--output-schema同时打印完整输出 JSON Schemalist_command 参数--json输出机器可读的结构化 JSONlist_command 参数--resources一并列出资源list_command 参数--prompts一并列出提示词list_command 参数--transport/-t强制 URL 目标的传输类型http或sselist_command 参数--timeout连接超时秒list_command 参数--auth认证方式oauth、bearer token 字符串或nonelist_command 参数--command以 stdio 命令作为服务器目标list_command 参数# 包含完整输入/输出 Schema fastmcp list server.py --input-schema --output-schema # 机器可读 JSON适合脚本与 Agent 消费 fastmcp list server.py --json # 同时列出资源与提示词 fastmcp list server.py --resources --prompts默认输出把每个工具格式化为类似 Python 函数签名的一行由 format_tool_signature 生成必选参数显示为name: type可选参数显示为name: type 默认值无默认值时显示...若存在输出 Schema 则追加- 返回类型。类型映射表_JSON_SCHEMA_TYPE_MAPclient.py 第 32-40 行把 JSON Schema 类型翻译为 Python 风格string→str、integer→int、number→float、boolean→bool、array→list、object→dictanyOf合并类型则显示为str | int这样的联合类型。--json模式下工具序列化为{name, description, inputSchema, outputSchema}列表见 _tools_to_json同时传入--resources/--prompts时JSON 根对象中会附带resources与prompts数组。三、fastmcp call调用工具、读取资源、渲染提示词fastmcp call默认把第二个位置参数当作工具名来调用如果它包含://则视为资源 URI走read_resource传入--prompt则当作提示词名走get_prompt。分发逻辑见 call_command。3.1 以 keyvalue 传参自动类型转换# 字符串参数 fastmcp call server.py greet nameWorld # 整数参数limit5 会自动转为 int fastmcp call server.py add a3 b4类型转换是自动的CLI 先通过client.list_tools()拿到该工具的inputSchema再对每个keyvalue按属性类型做强制转换。转换规则在 coerce_value 中实现Schema 类型转换规则integerint(raw)失败报Expected integernumberfloat(raw)5转为5.0booleantrue/1/yes不区分大小写→Truefalse/0/no→Falsearray/object按 JSON 解析json.loads失败报Expected JSON array/object其他 / 缺失类型原样保留为字符串如42在 string 类型下仍是423.2 复杂参数单 JSON 对象与 --input-json当工具需要嵌套结构数组、字典、任意对象时keyvalue表达式不够用有两种方式# 方式一单个位置参数直接传 JSON 对象必须是第一个且唯一的裸参数、以 { 开头 fastmcp call server.py create_item {name: Widget, tags: [a, b]} # 方式二--input-json 作为基础参数keyvalue 覆盖个别字段 fastmcp call server.py search --input-json {query: hello, limit: 5} limit10合并逻辑见 parse_tool_arguments--input-json必须先解析为一个 JSON 对象否则报错退出然后逐个应用keyvalue覆盖——因此上例中limit最终为 10。注意--input-json已提供时位置参数中的 JSON 对象不再特殊处理会被当作keyvalue语法校验并报错对应测试 test_json_positional_ignored_when_input_json_set。3.3 读取资源与渲染提示词# 读取资源目标包含 :// 即视为资源 URI fastmcp call server.py resource://docs/readme # 渲染提示词--prompt 将目标视为提示词名 fastmcp call server.py summarize --prompt topicweather资源读取实现于 _handle_resource文本资源直接打印文本二进制资源以[Blob: mimeType, ~大小 bytes]摘要显示。提示词渲染实现于 _handle_prompt提示词参数复用parse_tool_arguments但传入空 Schema因此所有值都保持字符串输出按role:加内容逐条打印。3.4 JSON 输出与结果序列化fastmcp call server.py add a3 b4 --json--json下结果序列化为{content: [...], is_error: bool, structured_content: ...}见 _call_result_to_dict其中 content 数组的元素形如{type: text, text: ...}、{type: image, mimeType: ..., data: ...}等见 _content_block_to_dict。资源与提示词的--json输出则分别是内容块数组与{description, messages}对象。若调用结果为错误is_errorTrue文本模式下以红色 Error 前缀输出--json模式下仍返回完整结构体且进程退出码为 1client.py 第 537-538 行。一个值得注意的安全细节CLI 对服务器返回的文本做了终端转义处理_sanitize_untrusted_textRich 标记被转义、控制字符被编码为\xNN避免恶意服务器内容注入终端样式或控制序列——相关行为有测试 test_escapes_rich_markup_and_control_chars 覆盖。四、服务器目标Server Targets解析规则两条命令共享同一套目标定位逻辑resolve_server_spec支持的六类目标如下目标示例解析行为HTTP/HTTPS URLhttp://localhost:8000/mcp原样传给Client--transport sse时自动把 URL 改写为以/sse结尾无重复后缀、容忍尾斜杠见测试 test_transport_sse_rewrites_urlPython 文件server.py解析为fastmcp run server.py --no-banner的 stdio 进程MCPConfig JSONmcp.json要求 JSON 顶层含mcpServers键若是 FastMCP 服务器配置如fastmcp.json则报错并提示先fastmcp run再查询见 _resolve_json_specstdio 命令--command npx -y mcp/server用shlex.split拆分后构造StdioTransport(command, args)见 _build_stdio_from_command支持引号内带空格的包名已发现的名字weather或source:name通过 resolve_name 在配置中查找并转为对应 transport目标解析的几条边界规则均有测试覆盖服务器目标与--command互斥同时提供会报错退出目录不会被当作文件路径resolve_server_spec(某个目录)会报错test_directory_exits.json文件要求存在且 JSON 合法否则报错退出。对于已配置服务器的名字引用支持用source:name精确指定来源例如claude-code:my-server、cursor:weather。裸名字如weather在多个来源重复时会提示歧义并列出可用的限定名discovery.py 第 376-383 行。运行fastmcp discover可查看当前机器上所有可用名字。SSE 服务器通过--transport sse指定fastmcp list http://localhost:8000/mcp --transport sse五、认证HTTP 目标默认走 OAuthHTTP/HTTPS 目标默认自动启用 OAuth 认证服务器不需要认证时该流程自动跳过no-op。认证决策在 _build_client 中目标是 HTTP/HTTPS URL 或 HTTP/SSE transport 时默认authoauth显式传--auth none可完全禁用认证--auth也可传入 bearer token 字符串stdio、MCPConfig JSON 目标不套用顶层认证MCPConfig 内部按服务器各自管理认证。# 服务器无需认证时禁用 OAuth 以避免多余的交互 fastmcp call http://server/mcp tool --auth none相关行为由 test_build_client 测试组 验证HTTP 目标默认带上 auth、authnone明确禁用、stdio 目标无 auth。六、fastmcp discover发现配置好的服务器fastmcp discover扫描本机编辑器与项目配置找出其中定义的所有 MCP 服务器并给出可直接用于list/call的名字。# 查看全部 fastmcp discover # 按来源过滤可多次指定 fastmcp discover --source claude-code fastmcp discover --source cursor --source gemini --json # JSON 输出 fastmcp discover --json扫描来源与对应配置文件实现于 discovery.py 的各_scan_*函数来源名扫描位置说明claude-desktop各平台 Claude Desktop 配置macOS~/Library/Application Support/Claude、Linux$XDG_CONFIG_HOME/Claude、Windows%APPDATA%/Claude下的claude_desktop_config.json_scan_claude_desktopclaude-code~/.claude.json的全局mcpServers与匹配当前目录的projects.cwd.mcpServers_scan_claude_codecursor从当前目录向上逐级查找.cursor/mcp.json到主目录或根目录为止_scan_cursor_workspacegemini用户级~/.gemini/settings.json与项目级.gemini/settings.json_scan_geminigoose~/.config/goose/config.yamlWindows 为%APPDATA%/Block/goose/configschema 为extensionstype: stdio的扩展被转换为mcpServers格式_scan_gooseproject当前目录下的./mcp.json_scan_project_mcp_json扫描器会把各家编辑器字段规范化为统一格式_normalize_server_entryGemini 的httpUrl映射为urlClaude Code 等来源的type映射为transport。每个发现结果DiscoveredServer提供name、source、qualified_name即source:name、transport_summary如stdio: npx -y ...或http: http://...和config_pathdiscover --json即输出这些字段的数组。当没有发现任何服务器时discover会打印它搜索过的全部位置清单便于排查。七、推荐工作流与脚本化集成7.1 交互式三连# 1. 看本机配置了哪些服务器 fastmcp discover # 2. 看某台服务器有哪些工具 fastmcp list weather # 3. 调用工具 fastmcp call weather get_forecast cityLondon7.2 作为 LLM Agent 的 MCP 桥官方文档docs/cli/client.mdx明确指出对于能执行 shell 命令但没有原生 MCP 支持的 LLM Agentfastmcp list --json与fastmcp call --json构成一个干净的桥接层——Agent 先以--json获取带完整 Schema 的工具清单再以--json调用工具并拿到结构化结果。这也正是本 SKILLfrontmatter 的description字段声明其适用场景的原因查询服务器能力、调用工具、把 MCP 服务器集成进工作流。7.3 本地示例演练仓库提供了大量可直接作为目标的示例服务器例如examples/echo.py同时定义工具echo_tool、资源echo://static/echo://{text}、提示词echo最适合体验list --resources --prompts与call --promptexamples/get_file.py演示File类型工具可体验--json下 image/blob 类结果的序列化examples/simple_echo.py、examples/complex_inputs.py覆盖简单与复杂嵌套参数两种调用形态。演练命令参考# 列出 echo 服务器的全部能力 fastmcp list examples/echo.py --resources --prompts --input-schema # 调用工具自动类型转换 fastmcp call examples/echo.py echo_tool texthello # 读取资源 fastmcp call examples/echo.py echo://static # 渲染提示词 fastmcp call examples/echo.py echo --prompt texthello --json八、与相邻工具的关系fastmcp generate-clilist/call是通用命令每次都要从零指定服务器、工具名和参数fastmcp generate-cli则更进一步——连接服务器、读取工具 Schema 后生成一个每个工具都是独立子命令、带类型化参数和 tab 补全的 Python CLI 脚本见 docs/cli/generate-cli.mdx。fastmcp-remote对于需要本地 stdio 命令但想连接远程 HTTP 服务器的 MCP 宿主可参考 fastmcp_remote 包 的桥接方案fastmcp list/call专注于终端下的直接检查与调用见 docs/cli/client.mdx。fastmcp inspect/fastmcp runrun是本地启动服务器与临时脚本的手段list/call面向消费方视角fastmcp run --no-banner是list server.py底层的实际执行命令见 cli.py 中的 run 命令。九、小结fastmcp list、fastmcp call与fastmcp discover三件套构成了一个与语言、框架无关的 MCP 交互层discover把散落在各编辑器配置里的服务器统一收编为可引用名字list把服务器能力翻译成带类型的签名与完整 JSON Schemacall则以自动类型转换、JSON 参数、资源读取、提示词渲染和结构化输出覆盖了绝大多数调用场景。无论是交互排障、脚本自动化还是为 LLM Agent 提供 MCP 桥接这套 CLI 都值得作为首选入口。相关源码与测试位于 fastmcp_slim/fastmcp/cli/client.py、fastmcp_slim/fastmcp/cli/discovery.py 与 tests/cli/test_client_commands.py可进一步深入研读。【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考