MCP Inspector: Interactive Debugging Tool for MCP Servers
Quick Answer
- What it is: MCP Inspector is an interactive debugging UI for testing MCP (Model Context Protocol) servers during development. It lets you inspect resources, test tools, and view notifications without writing client code.
- First check: Ensure Node.js (v18+) and npm are installed (
node -v && npm -v). The tool runs vianpxwith no global install needed. - Minimal command:
npx @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /path/to/directory— this launches the Inspector UI and a sample filesystem server. - Environment boundary: Development only. Never use in production — the Inspector exposes server internals, has no authentication, and keeps persistent connections that consume resources.
What Problem It Solves
MCP servers are background processes that communicate with AI clients (like Claude Desktop or Cursor) using the Model Context Protocol. When a server misbehaves — a tool call fails, a resource doesn't load, or a prompt returns unexpected data — diagnosing the issue is difficult without a dedicated debugging interface.
MCP Inspector solves this by providing a browser-based UI that:
- Lists all available resources, prompts, and tools exposed by the server
- Lets you invoke tools and view their responses in real time
- Shows server notifications and logs as they arrive
- Allows you to set custom environment variables before the server starts
Installation and Quick Start
No installation is required. MCP Inspector runs directly via npx:
BASHnpx @modelcontextprotocol/inspector <command> [options]
The <command> parameter specifies how to launch the target MCP server. Supported values:
| Command | Use Case | Example |
|---|---|---|
npx | Inspect an npm-published MCP server | npx @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /tmp |
uvx | Inspect a PyPI-published MCP server | npx @modelcontextprotocol/inspector uvx mcp-server-git |
node | Inspect a local Node.js server | npx @modelcontextprotocol/inspector node path/to/server/index.js |
uv | Inspect a local Python server | npx @modelcontextprotocol/inspector uv --directory /path/to/project |
After running the command, open the URL printed in the terminal (typically http://localhost:5173) in your browser.
Parameters and Environment Variables
CLI Parameters
| Parameter | Required | Description |
|---|---|---|
command | Yes | The launcher method (npx, uvx, node, uv) |
package-name | No | npm or PyPI package name (used with npx or uvx) |
path/to/server/index.js | No | Local server entry point (used with node) |
--directory | No | Root directory of local Python server (used with uv) |
args | No | Additional arguments passed to the server being inspected |
Environment Variables in the Inspector UI
The Inspector's "Server connection pane" in the web interface allows you to add custom environment variables as key-value pairs. These are passed to the MCP server process when it starts. This is useful for testing servers that require specific configuration (API keys, database URLs, etc.).
Common Errors and Fixes
npx: command not found
Node.js and npm are not installed. Verify with node -v and npm -v. If missing, install Node.js (v18 or later) from the official website.
Error: Cannot find module '@modelcontextprotocol/inspector'
The npm package failed to download, likely due to network issues. Clear the npm cache and retry:
BASHnpm cache clean --force npx -y @modelcontextprotocol/inspector <command>
The -y flag forces re-download.
Connection refused / ECONNREFUSED
The Inspector cannot connect to the target MCP server. Check that:
- The server command is correct and the server starts without errors
- File paths exist and are accessible
- For local servers, the entry point file is valid JavaScript or Python
Inspector UI not loading (blank page)
Possible port conflict or browser cache issue. Try:
- Close other processes using port 5173
- Open the URL in an incognito/private browser window
- Specify an alternative port:
npx @modelcontextprotocol/inspector --port 3001 <command>
Production Notes and Security Checks
MCP Inspector is a development tool with several critical limitations:
- No authentication: Anyone who can reach the Inspector's web interface can control the debugged server
- Network exposure: The UI binds to localhost by default, but misconfiguration could expose it externally
- Resource overhead: The Inspector maintains persistent connections and logs all communication, increasing memory and CPU usage
- File system exposure: When using
server-filesystem, the Inspector exposes the specified directory's contents
Security recommendations:
- Use only on local development machines
- Close the Inspector when debugging is complete
- Do not bind to
0.0.0.0or expose the port through firewalls - Avoid inspecting servers that access production data or credentials
FAQ
Q: Can MCP Inspector test remote MCP servers?
A: Yes, if the remote server exposes an MCP-compatible endpoint via SSE or WebSocket transport. Use the --transport flag to specify the transport type. However, remote debugging introduces security risks — only use it in controlled network environments.
Q: How do I view detailed logs captured by Inspector?
A: The "Notifications" panel in the web UI displays all server logs and notifications in real time. For more verbose debugging, set the DEBUG environment variable when starting the Inspector: DEBUG=* npx @modelcontextprotocol/inspector <command>.
Q: Does Inspector support custom environment variables for the server?
A: Yes. The "Server connection pane" in the web interface allows you to add key-value environment variables that are passed to the MCP server process. This is useful for testing servers that require specific configuration like API keys or database URLs.