mcp-explorer

CLI tool for exploring MCP servers

Installation

Install this tool using pip:

pip install mcp-explorer

Usage

List the tools exposed by a streamable HTTP MCP server:

mcp-explorer list https://agentic-mermaid.dev/mcp

The default output is deliberately compact: each tool is shown as a signature and a one-line description. Use -N or --no-truncate for full descriptions and detailed parameter metadata:

mcp-explorer list -N https://agentic-mermaid.dev/mcp

This forces the current MCP 2 stateless protocol by default. Use --legacy to force the older initialize-handshake protocol instead:

mcp-explorer list https://agentic-mermaid.dev/mcp --legacy

Use --json to output the complete tool definitions, including their input schemas:

mcp-explorer list https://agentic-mermaid.dev/mcp --json

Inspect a single tool in detail:

mcp-explorer inspect https://agentic-mermaid.dev/mcp render_svg

This displays the tool's complete description, nested input and output schemas, annotations, execution metadata, icons, and _meta. Use --json for the complete tool definition as a single JSON object:

mcp-explorer inspect https://agentic-mermaid.dev/mcp render_svg --json

Call a tool by passing its arguments as a JSON object:

mcp-explorer call \
  https://agentic-mermaid.dev/mcp \
  verify \
  '{"source":"graph TD; A-->B"}'

Alternatively, use repeatable -a/--argument NAME VALUE options:

mcp-explorer call \
  https://agentic-mermaid.dev/mcp \
  render_svg \
  -a source 'graph TD; A-->B' \
  -a options '{"padding":24}'

Use - to read the raw JSON object from standard input:

mcp-explorer call URL TOOL - < arguments.json

When raw JSON and -a are combined, individual arguments override matching top-level keys in the JSON object and later -a values win. Values are interpreted using the tool's input schema: strings remain literal, while numbers, booleans, arrays, objects, and null are parsed as JSON. The assembled arguments are validated against the input schema before the tool is called.

Use --json to print the tool's structuredContent as JSON. If the result has no structured content, this falls back to printing the first text content block:

mcp-explorer call \
  https://datasette.simonwillison.net/-/mcp \
  execute_sql \
  -a database simonwillisonblog \
  -a sql 'select count(*) from blog_entry' \
  --json

Use --raw for the complete MCP CallToolResult as JSON:

mcp-explorer call URL TOOL -a name value --raw

List every prompt exposed by a server:

mcp-explorer prompts URL
mcp-explorer prompts URL --json
mcp-explorer prompts URL --legacy

The human-readable output includes prompt arguments and whether each is required. JSON output contains the complete prompt definitions.

List every directly-addressable resource exposed by a server:

mcp-explorer resources URL
mcp-explorer resources URL --json
mcp-explorer resources URL --legacy

The human-readable output includes each resource URI, MIME type, size, and description when available. Both commands follow pagination until all results have been collected.

Use info to show the selected protocol, negotiation mechanism, supported versions, server identity, capabilities, and instructions:

mcp-explorer info https://agentic-mermaid.dev/mcp
mcp-explorer info https://agentic-mermaid.dev/mcp --json

Use doctor to check both stateless and legacy compatibility. The selected mode is checked first and determines the exit status:

mcp-explorer doctor https://agentic-mermaid.dev/mcp
mcp-explorer doctor https://agentic-mermaid.dev/mcp --legacy

Every command accepts --json and --stateless/--legacy. These options can appear anywhere after the command name. The call command also accepts --raw.

For help, run:

mcp-explorer --help

You can also use:

python -m mcp_explorer --help

Development

To contribute to this tool, first checkout the code. Run the tests like this:

cd mcp-explorer
uv run pytest

And the development version of the tool like this:

uv run mcp-explorer --help

To update the --help reference in the README:

uv run cog -r README.md

Command reference

mcp-explorer list --help

Usage: mcp-explorer list [OPTIONS] URL

  List the tools exposed by an MCP server at URL.

Options:
  -N, --no-truncate       Show full descriptions and detailed parameters.
  --json                  Output JSON.
  --stateless / --legacy  Force stateless MCP 2 (default) or the legacy
                          initialize handshake.
  --help                  Show this message and exit.

mcp-explorer prompts --help

Usage: mcp-explorer prompts [OPTIONS] URL

  List the prompts exposed by an MCP server at URL.

Options:
  --json                  Output JSON.
  --stateless / --legacy  Force stateless MCP 2 (default) or the legacy
                          initialize handshake.
  --help                  Show this message and exit.

mcp-explorer resources --help

Usage: mcp-explorer resources [OPTIONS] URL

  List the resources exposed by an MCP server at URL.

Options:
  --json                  Output JSON.
  --stateless / --legacy  Force stateless MCP 2 (default) or the legacy
                          initialize handshake.
  --help                  Show this message and exit.

mcp-explorer inspect --help

Usage: mcp-explorer inspect [OPTIONS] URL TOOL_NAME

  Inspect one tool exposed by an MCP server at URL.

Options:
  --json                  Output JSON.
  --stateless / --legacy  Force stateless MCP 2 (default) or the legacy
                          initialize handshake.
  --help                  Show this message and exit.

mcp-explorer call --help

Usage: mcp-explorer call [OPTIONS] URL TOOL_NAME [ARGUMENTS_JSON]

  Call a tool with optional JSON and individual arguments.

Options:
  -a, --argument NAME VALUE  Set one tool argument; repeat for multiple
                             arguments.
  --raw                      Output the complete MCP CallToolResult as JSON.
  --json                     Output JSON.
  --stateless / --legacy     Force stateless MCP 2 (default) or the legacy
                             initialize handshake.
  --help                     Show this message and exit.

mcp-explorer info --help

Usage: mcp-explorer info [OPTIONS] URL

  Show protocol and metadata for an MCP server at URL.

Options:
  --json                  Output JSON.
  --stateless / --legacy  Force stateless MCP 2 (default) or the legacy
                          initialize handshake.
  --help                  Show this message and exit.

mcp-explorer doctor --help

Usage: mcp-explorer doctor [OPTIONS] URL

  Check stateless and legacy compatibility for an MCP server at URL.

Options:
  --json                  Output JSON.
  --stateless / --legacy  Force stateless MCP 2 (default) or the legacy
                          initialize handshake.
  --help                  Show this message and exit.