npm package: @iotpebble/mcpx
Description: The MCP Explorer CLI — explore, test, and debug MCP servers from your terminal
Latest version: 0.1.0

# mcpx — The MCP Explorer CLI

> Explore, test, and debug MCP servers from your terminal. Zero friction.

**mcpx** is a fast, keyboard-driven CLI tool for developers building and testing [Model Context Protocol](https://modelcontextprotocol.io) servers. No GUI needed — just your terminal.

```bash
npx mcpx ./my-server.js
```

![mcpx demo](demo.gif)

## Why mcpx?

The MCP ecosystem is exploding, but developer tooling hasn't kept up:
- The official **Inspector** is a heavyweight web UI
- **MCP Explorer** is a GUI desktop app
- Neither is fast enough for developers who live in the terminal

**mcpx** gives you instant server exploration, tool execution, health checks, and benchmarks — all from the command line.

## Install

```bash
# Use instantly with npx (no install needed)
npx mcpx ./my-server.js

# Or install globally
npm install -g mcpx
```

## Usage

### Interactive Explorer (default)

Launch the interactive TUI to browse tools, resources, and prompts:

```bash
mcpx ./my-server.js
mcpx npx @modelcontextprotocol/server-filesystem /tmp
mcpx --sse http://localhost:3000/mcp
```

Navigate with `j`/`k`, press `Enter` to select a tool, type JSON args, and execute. `Esc` to go back, `q` to quit.

### List Tools, Resources & Prompts

```bash
mcpx list tools ./my-server.js
mcpx list resources ./my-server.js
mcpx list prompts ./my-server.js
mcpx list all ./my-server.js

# JSON output for scripting
mcpx list tools --json ./my-server.js | jq '.[].name'
```

### Call a Tool

```bash
mcpx call myTool '{"key": "value"}' ./my-server.js
mcpx call list_allowed_directories '{}' npx @modelcontextprotocol/server-filesystem /tmp

# JSON output
mcpx call myTool '{}' --json ./my-server.js
```

### Health Check

Validate that a server initializes correctly, lists capabilities, and has valid schemas:

```bash
mcpx test ./my-server.js
mcpx test npx @modelcontextprotocol/server-filesystem /tmp
```

Returns non-zero exit code on failure — perfect for CI.

### Benchmark

Measure server latency for `listTools`, `listResources`, `listPrompts`, and tool calls:

```bash
mcpx bench ./my-server.js
mcpx bench -n 50 ./my-server.js   # 50 iterations
```

Output includes min, max, avg, and p95 latency.

### Auto-discover from Config

Load MCP servers directly from your Claude Desktop config:

```bash
# List all configured servers
mcpx --config

# Connect to a named server
mcpx --config --server filesystem list tools
mcpx --config --server filesystem

# Use a custom config path
mcpx --config ~/my-config.json --server myserver test
```

## Transport Support

| Transport | Flag | Example |
|-----------|------|---------|
| stdio (default) | — | `mcpx ./server.js` |
| SSE | `--sse` | `mcpx --sse http://localhost:3000/sse` |
| Streamable HTTP | `--http` | `mcpx --http http://localhost:3000/mcp` |

## Examples

```bash
# Explore the official filesystem server
mcpx npx @modelcontextprotocol/server-filesystem /tmp

# List all tools from a local server
mcpx list tools node my-server.js

# Call a tool and pipe results
mcpx call search_files '{"path": "/tmp", "pattern": "*.txt"}' --json \
  npx @modelcontextprotocol/server-filesystem /tmp | jq '.result'

# CI health check
mcpx test ./my-server.js || echo "Server unhealthy!"

# Benchmark before deploying
mcpx bench ./my-server.js -n 100
```

## License

MIT