CLI 客户端

每次 CLI 运行都会连接到服务器，调用你通过 --method 指定的单个请求，打印结果，然后退出。这使其非常适合 CI 流水线、Shell 单行命令，以及需要立即验证服务器更改的编程代理。

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

如果要针对同一服务器运行多条命令，或执行跨越一个会话的流程（任务、订阅、诱导）怎么办？mcpdo 连接客户端会连接一次，并在命令之间保持连接打开。

下面的示例使用已安装的 mcp-inspector 二进制文件。如果未进行全局安装，请像上面一样，在每条命令前加上 npx @modelcontextprotocol/inspector。

选择服务器

CLI 接受位置参数命令（stdio）、--server-url（HTTP/SSE），或从目录或配置文件中选择命名服务器：

# stdio：所有位置参数内容都是要启动的命令
mcp-inspector --cli node build/index.js --method tools/list

# HTTP
mcp-inspector --cli https://api.example.com/mcp --transport http --method tools/list

# 从文件中读取
mcp-inspector --cli --config ./mcp.json --server myserver --method tools/list

当服务器来自文件时，其每个服务器的设置（请求头、超时、OAuth、协议时代和根目录）将应用于连接，其解析方式与 TUI 和 Web 客户端完全一致。--header 标志会在本次运行中覆盖文件中的请求头，同时保留其中的超时和 OAuth 设置。后续示例会将你所使用的上述任一种形式，以及其 --transport 或 --config/--server 标志，统称为 <server>。

**配置文件是为运行提供根目录的唯一持久方式：**没有 roots 标志，并且 CLI 没有 roots/set 方法。为服务器配置的根目录会在连接时公布，因此调用 roots/list 的服务器（例如 @modelcontextprotocol/server-filesystem，它会通过此调用了解其允许访问的目录）可以获取这些根目录。

请参阅配置和标志，了解 --catalog 与 --config、-- 分隔符以及通用服务器选择标志。

方法

`--method`	必需的配套参数	说明
`initialize`	无	仅连接探测：`{serverInfo, protocolVersion, capabilities, instructions}`。
`tools/list`	无	`--strict` 会将其 schema 可移植性检查转为门禁（请参阅CI 门禁）。
`tools/call`	`--tool-name`，以及可选的 `--tool-arg` / `--tool-args-json`
`resources/list`	无
`resources/read`	`--uri`
`resources/templates/list`	无
`resources/directory/read`	`--uri`，以及可选的 `--cursor`	一次一页；传回上一页的 `nextCursor`。
`prompts/list`	无
`prompts/get`	`--prompt-name`，以及可选的 `--prompt-args`
`logging/setLevel`	`--log-level`	仅适用于旧版时代；现代服务器会改为按请求选择加入。
`skills/list`	无	`--verify` 会检查返回的技能（请参阅CI 门禁）。
`skills/get`	`--uri`	使用相同的 `--verify` 选项。
`servers/list`	无	在不连接任何对象的情况下读取目录。
`servers/show`	`--server`	针对单个条目执行相同操作。
`servers/add`	`--server`，以及位置参数目标或 `--server-url`	在不连接的情况下写入目录（请参阅编辑目录）。
`servers/edit`	`--server`，以及要修改的内容	同上。
`servers/remove`	`--server`	在不连接的情况下移除目录条目。

仅限流或会话的方法（例如 logging/tail）会被拒绝，因为退出的进程无法保持流处于打开状态。

传递参数

--tool-arg 接受 key=value，并在能够解析时通过 JSON 解析来强制转换每个值，因此 count=1 和 zip=10001 都会发送数字。无效 JSON（例如 zip=012 或裸词）会作为字符串发送，而随后会根据工具输入 schema 为该属性声明的类型转换字符串值，因此对数字类型的 zip 使用 zip=012 仍会发送 12：

mcp-inspector --cli <server> --method tools/call --tool-name mytool \
  --tool-arg key=value --tool-arg count=1 --tool-arg 'options={"format":"json"}'

--tool-args-json 一次性接受完整的参数对象，跳过 key=value 解析，因此 {"zip":"10001"} 会发送字符串 "10001" 而不是数字。schema 转换仍适用于字符串值，因此只有当 schema 将该属性声明为字符串（或未声明该属性）时，才能保持字符串不变。两个标志不能同时使用：

mcp-inspector --cli <server> --method tools/call --tool-name mytool \
  --tool-args-json '{"zip":"10001"}'

输出

--format text（默认）以适合人类阅读的格式美化输出。--format json 会在 stdout 上输出单个 JSON 对象，不包含任何横幅信息，因此整个输出可以直接通过管道传递：

mcp-inspector --cli <server> --method tools/list --format json | jq '.result.tools[].name'

探测 MCP 应用

--app-info 会报告某个工具是否提供 MCP 应用 UI（包括其 ui:// 资源、CSP 和权限），而不会调用该工具，因此流水线可以在调用任何工具之前决定是否需要浏览器：

# 一个工具 -> 一行 JSON
mcp-inspector --cli <server> --method tools/call --tool-name my_tool --app-info
# {"hasApp":true,"toolName":"my_tool","resourceUri":"ui://...","csp":{...},"permissions":{...}}

# 所有工具 -> NDJSON，每个工具一行，通过单个连接传输
mcp-inspector --cli <server> --method tools/list --app-info | jq -c 'select(.hasApp)'

退出代码用于区分不同结果：提供应用的工具退出码为 0，不提供应用的工具退出码为 2，缺少的工具退出码为 5，因此拼写错误不会被误认为“没有应用”。探测失败（UI 资源无法读取、resourceUri 格式错误）会记录在 resourceError 字段中，而不会中止操作，因此单个异常工具不会导致整个列表处理失败。 CLI 无法渲染 App，因此默认不会在 initialize 时声明 MCP Apps 扩展。只向声明支持 App 的客户端公开其 App 工具的服务器会因此看起来没有 App（退出码 2）。添加 --advertise-apps 可让本次运行声明该扩展。

tools/list --app-info 始终输出 NDJSON（每个工具一行），无论 --format 的值是什么；--format json 只会调整 tools/call --app-info 的单个工具输出格式。

退出代码和错误信封

每个非零退出代码都对应一个稳定的失败类别，因此调用方无需抓取文字描述即可根据_原因_进行分支处理：

代码	含义
`0`	成功。
`1`	用法错误或意外错误（兜底项），包括无法读取的机密信息存储或 OAuth 状态文件。
`2`	工具中未找到 MCP App（`--app-info` 探测）。
`3`	服务器要求身份验证（HTTP 401/403，或 SDK 授权错误）。
`4`	服务器无法访问（DNS、连接被拒绝、超时、`fetch failed`）。
`5`	工具错误：`tools/call` 返回 `isError: true`，或未找到该工具。
`6`	`--strict` 发现错误级别的工具 schema 可移植性问题。
`7`	`--verify` 发现违反 SEP-2640 的技能（一致性、摘要或大小不匹配）。
`8`	`--verify` 无法在读取限制内检查所有技能。
`9`	`--verify --require-digests` 发现某个技能未声明摘要。

在任何非零退出的情况下，CLI 还会向 stderr 写入一行 JSON：

{
  "error": {
    "code": "auth_required",
    "message": "Unauthorized",
    "status": 401,
    "url": "https://api.example/mcp"
  }
}

该信封始终包含 code 和 message，并在已知时附带 cause（底层错误，例如 DNS 失败）、status（HTTP 状态）和 url。URL 中的查询字符串机密信息会被清理。code 是失败的稳定名称，例如 auth_required、unreachable、tool_not_found、tool_is_error、no_app、schema_unportable、store_unavailable、oauth_state_unrecognized 或兜底的 error。由于它只有一行，调用方可以使用 2>&1 | tail -1 | jq .error 对其进行解析。返回 isError: true 的 tools/call 仍会打印其载荷，但会以 5 退出，因此 && 链不会在调用失败时继续执行。

脚本中的授权

默认情况下，CLI 运行与 TUI 相同的回环 OAuth 流程：打开浏览器并等待 localhost 回调，而 CI 作业无法完成此操作。以下两个标志可让非交互式运行变得可预测：

--stored-auth-only：永不启动交互式 OAuth 或升级验证，也永不自动打开浏览器。如果共享存储中存在令牌，则使用这些令牌；否则立即失败并返回 auth_required。这是 CI 所需的标志。
--use-stored-auth：复用 Web Inspector 已在此机器上获取的令牌；如果存储了刷新令牌，则会先刷新令牌。它按 URL 查找令牌，因此需要 --server-url。

如果两个标志都未使用，且 stdin 或 stderr 上没有 TTY，CLI 会快速失败并返回 auth_required，而不是在无人完成的回调上挂起十五分钟。完整流程、Web 到 CLI 的交接以及 --print-handoff，请参阅授权。

配方

在 CI 中验证服务器

set -euo pipefail

# 如果无法访问服务器或服务器未提供该工具，则构建失败
mcp-inspector --cli --config ./ci-servers.json --server my-server \
  --stored-auth-only --method tools/list --format json \
  | jq -e '.result.tools | map(.name) | index("get_weather")' > /dev/null

CI 门禁

三个标志会将检查转为非零退出，并分别使用专属代码，让作业可以区分失败类型：

--strict（与 tools/list 一起使用）：在 stderr 上完整报告工具 schema 可移植性问题（路径、问题和建议修复），如果存在错误级别问题则以 6 退出。不使用该标志时，tools/list 只打印一行计数。使用 --format json 时，发现结果会作为 schemaFindings 合并到输出中
--verify（与 skills/list 或 skills/get 一起使用）：运行 SEP-2640 一致性和摘要检查，在 stdout 上为每个技能写入一份 JSON 报告；发现违规时以 7 退出，如果读取限制使其在检查所有技能前停止则以 8 退出。--skill-catalog-max-skills 和 --skill-catalog-max-bytes 可设置这些限制
--require-digests（与 --verify 一起使用）：对于未声明任何摘要的技能以 9 退出，而不是将其报告为无法验证并以 0 退出

mcp-inspector --cli <server> --method tools/list --strict > /dev/null
mcp-inspector --cli <server> --method skills/list --verify --require-digests

根据失败类别进行分支处理

if out=$(mcp-inspector --cli "$URL" --transport http --method tools/list 2>err.json); then
  echo "$out"
else
  case $? in
    3) echo "needs auth: run the web inspector once to sign in" ;;
    4) echo "server unreachable" ;;
    *) jq .error < err.json ;;
  esac
fi

对所有具有 UI 的工具执行冒烟测试

mcp-inspector --cli "$URL" --transport http --method tools/list --app-info \
  | jq -r 'select(.hasApp) | .toolName'

在不建立连接的情况下检查目录

mcp-inspector --cli --catalog ~/.mcp-inspector/mcp.json --method servers/list
mcp-inspector --cli --catalog ~/.mcp-inspector/mcp.json --method servers/show --server my-server

servers/show 会隐藏包含机密信息的字段（env 值、敏感请求头、 OAuth 客户端机密），但不会清除嵌入服务器 url（用户信息或查询令牌）或 stdio args 中的凭据。在将原始 URL 和 detail 字段粘贴到 issue 之前，请将其视为敏感信息。

编辑目录

servers/add、servers/edit 和 servers/remove 会在不连接任何对象的情况下写入目录。它们使用与 Web 客户端服务器列表相同的代码，因此 env 值和客户端密钥会像从 UI 写入时一样进入机密信息存储，运行中的 Web 客户端也会获取该变更。

# 添加：位置参数目标或 --server-url 描述条目，而不是要连接的服务器
mcp-inspector --cli node build/index.js -e API_KEY=secret --method servers/add --server my-server

# 编辑：修改目标、-e、--cwd、--header 或 --protocol-era，或重命名条目
mcp-inspector --cli --method servers/edit --server my-server --rename my-renamed-server

# 移除条目及其存储的机密信息
mcp-inspector --cli --method servers/remove --server my-renamed-server

只有可写目录（--catalog、MCP_CATALOG_PATH 或默认目录）可以写入；--config 会被拒绝。使用内存机密信息存储时，提供 -e 值的写入（以及重命名）会被拒绝，因为运行结束后机密信息会丢失。

代理

连接到远程 HTTP/SSE 服务器时，会遵循约定的代理变量：HTTPS_PROXY / HTTP_PROXY（及其小写形式）用于选择代理，NO_PROXY 用于排除特定主机。无需设置 Inspector 专用标志，并且代理代理器会延迟加载，因此不使用代理时不会产生任何开销。Web 客户端的后端同样如此。

开始使用

关于 MCP

使用 MCP 进行开发

开发者工具

示例

选择服务器

方法

传递参数

输出

探测 MCP 应用

退出代码和错误信封

脚本中的授权

配方

在 CI 中验证服务器

CI 门禁

根据失败类别进行分支处理

对所有具有 UI 的工具执行冒烟测试

在不建立连接的情况下检查目录

编辑目录

代理

​选择服务器

​方法

​传递参数

​输出

​探测 MCP 应用

​退出代码和错误信封

​脚本中的授权

​配方

​在 CI 中验证服务器

​CI 门禁

​根据失败类别进行分支处理

​对所有具有 UI 的工具执行冒烟测试

​在不建立连接的情况下检查目录

​编辑目录

​代理

选择服务器

方法

传递参数

输出

探测 MCP 应用

退出代码和错误信封

脚本中的授权

配方

在 CI 中验证服务器

CI 门禁

根据失败类别进行分支处理

对所有具有 UI 的工具执行冒烟测试

在不建立连接的情况下检查目录

编辑目录

代理