Inspector CLI

Run the MCP Inspector locally with full control over configuration and auto-connect features.

Installation

No installation required! Use npx to run the inspector:

npx @mcp-use/inspector

Or install globally for frequent use:

npm install -g @mcp-use/inspector
mcp-inspect

Basic Usage

Start the inspector with default settings:

npx @mcp-use/inspector

This will:

Start the inspector server on port 8080 (or next available)
Automatically open your browser to http://localhost:8080
Display the dashboard ready for connections

Command-Line Options

`--url <url>`

Auto-connect to a specific MCP server on startup:

npx @mcp-use/inspector --url http://localhost:3000/mcp

Supported URL formats:

HTTP/HTTPS: http://localhost:3000/mcp
WebSocket: ws://localhost:3000/mcp or wss://example.com/mcp
Public servers: https://mcp.linear.app/mcp

The inspector will automatically connect to the specified server when it opens.

`--port <port>`

Specify the starting port for the inspector server:

npx @mcp-use/inspector --port 9000

Port selection behavior:

If specified port is available, uses it
If port is in use, finds next available port
Valid range: 1-65535

`--help`, `-h`

Display help information:

npx @mcp-use/inspector --help

Usage Examples

npx @mcp-use/inspector

# Output:
# 🚀 MCP Inspector running on http://localhost:8080
# 🌐 Browser opened

Development Workflow

Local MCP Server Testing

When developing an MCP server locally:

Start Your MCP Server

# In terminal 1
cd my-mcp-server
npm run dev

Server runs on http://localhost:3000/mcp

Start Inspector with Auto-Connect

# In terminal 2
npx @mcp-use/inspector --url http://localhost:3000/mcp

Inspector opens and connects automatically.

Develop and Test

Make changes to your server code
Server hot-reloads
Inspector maintains connection
Test new tools immediately

Multiple Server Testing

Test multiple MCP servers simultaneously:

# Start inspector without auto-connect
npx @mcp-use/inspector

# Then manually connect to multiple servers:
# - http://localhost:3000/mcp
# - http://localhost:4000/mcp
# - https://mcp.linear.app/mcp

All connections persist in the dashboard.

Package.json Scripts

Add inspector to your project’s scripts:

package.json

{
  "scripts": {
    "dev": "mcp-use dev",
    "inspect": "npx @mcp-use/inspector --url http://localhost:3000/mcp",
    "dev:all": "concurrently \"npm run dev\" \"npm run inspect\""
  }
}

Then run:

# Start both server and inspector
npm run dev:all

Environment Variables

The inspector respects these environment variables:

`PORT`

Default port for the inspector server:

PORT=9000 npx @mcp-use/inspector

`MCP_SERVER_URL`

Default MCP server URL (alternative to --url flag):

MCP_SERVER_URL=http://localhost:3000/mcp npx @mcp-use/inspector

`NODE_ENV`

Environment mode:

NODE_ENV=production npx @mcp-use/inspector

Docker Usage

Run inspector in a Docker container:

# Pull the image
docker pull mcpuse/inspector:latest

# Run with default settings
docker run -p 8080:8080 mcpuse/inspector:latest

# Run with environment variables
docker run -p 8080:8080 \
  -e MCP_SERVER_URL=http://host.docker.internal:3000/mcp \
  mcpuse/inspector:latest

Use host.docker.internal to connect to services running on your host machine from Docker.

Troubleshooting

Port Already in Use

Error:

Error: Port 8080 is already in use

Solutions:

Use a different port:
```
npx @mcp-use/inspector --port 9000
```

Find and kill the process using the port:

# macOS/Linux
lsof -ti:8080 | xargs kill -9

# Windows
netstat -ano | findstr :8080
taskkill /PID <PID> /F

Browser Doesn't Open

Possible causes:

Browser not found in PATH
Headless environment
Permission issues

Solution:Manually open the URL shown in terminal:

🚀 MCP Inspector running on http://localhost:8080

Auto-Connect Fails

Error:

Failed to connect to http://localhost:3000/mcp

Checklist:

✅ MCP server is running
✅ URL is correct (check protocol and path)
✅ Server is accessible from inspector
✅ CORS is properly configured on server

Test connection:

curl http://localhost:3000/mcp

Invalid URL Format

Error:

Error: Invalid URL format: localhost:3000/mcp

Solution:URLs must include protocol:

# ❌ Wrong
--url localhost:3000/mcp

# ✅ Correct
--url http://localhost:3000/mcp

Advanced Usage

Custom CORS Configuration

The inspector includes built-in CORS middleware for proxying requests:

// Inspector automatically handles:
// - Origin: *
// - Exposed Headers: All
// - Credentials: include

This allows connecting to MCP servers from different origins.

Health Check Endpoint

The inspector exposes a health check endpoint:

curl http://localhost:8080/inspector/health

# Response:
{"status": "ok"}

Useful for:

Load balancer health checks
Monitoring scripts
CI/CD pipelines

Proxy API

The inspector includes a proxy API for CORS-restricted servers:

# Proxy requests through inspector
curl http://localhost:8080/inspector/api/proxy/mcp

Inspector

CLI

Create App

CLI Usage

Inspector CLI

Installation

Basic Usage

Command-Line Options

`--url <url>`

`--port <port>`

`--help`, `-h`

Usage Examples

Development Workflow

Local MCP Server Testing

Multiple Server Testing

Package.json Scripts

Environment Variables

`PORT`

`MCP_SERVER_URL`

`NODE_ENV`

Docker Usage

Troubleshooting

Advanced Usage

Custom CORS Configuration

Health Check Endpoint

Proxy API

Next Steps

Features

Self-Hosting

Build docs developers (and LLMs) love

Inspector

CLI

Create App

​Inspector CLI

​Installation

​Basic Usage

​Command-Line Options

​--url <url>

​--port <port>

​--help, -h

​Usage Examples

​Development Workflow

​Local MCP Server Testing

​Multiple Server Testing

​Package.json Scripts

​Environment Variables

​PORT

​MCP_SERVER_URL

​NODE_ENV

​Docker Usage

​Troubleshooting

​Advanced Usage

​Custom CORS Configuration

​Health Check Endpoint

​Proxy API

​Next Steps

Features

Self-Hosting

Build docs developers (and LLMs) love

Inspector CLI

Installation

Basic Usage

Command-Line Options

`--url <url>`

`--port <port>`

`--help`, `-h`

Usage Examples

Development Workflow

Local MCP Server Testing

Multiple Server Testing

Package.json Scripts

Environment Variables

`PORT`

`MCP_SERVER_URL`

`NODE_ENV`

Docker Usage

Troubleshooting

Advanced Usage

Custom CORS Configuration

Health Check Endpoint

Proxy API

Next Steps