MCP Inspector

Una herramienta para desarrolladores para probar y depurar servidores MCP.

GitHub
11k
Prueba este MCPPatrocinado

Documentación

MCP Inspector

Una herramienta de desarrollo para inspeccionar servidores Model Context Protocol (MCP). Se distribuye como un único paquete, @modelcontextprotocol/inspector, que ofrece tres formas de inspeccionar un servidor:

  • Web — una aplicación de una sola página Vite + React + Mantine con un backend Node.
  • CLI — un cliente de línea de comandos programable para automatización, CI y bucles de retroalimentación rápidos para agentes.
  • TUI — una interfaz de terminal interactiva construida con Ink.

Los tres se ejecutan a través de un único binario global mcp-inspector:

npx @modelcontextprotocol/inspector          # web UI (default)
npx @modelcontextprotocol/inspector --cli    # CLI
npx @modelcontextprotocol/inspector --tui    # TUI

[!WARNING] El Inspector gestiona secretos — tokens OAuth, secretos de cliente OAuth y valores stdio env: — y los almacena en el llavero del sistema operativo, si está disponible, por defecto. En una máquina sin llavero — Linux sin libsecret o un Secret Service, sesiones headless y SSH, Termux y contenedores con un volumen montado — se guardan en ~/.mcp-inspector/secrets.json en su lugar, sin cifrar a menos que proporciones una clave. Consulta Dónde se almacenan los secretos para saber cómo recuperar un llavero, cifrar el archivo o mantener los secretos solo en memoria.

¿Actualizando desde v1? Lee la guía de migración v1 → v2 — las banderas de CLI, la nueva división --config vs. --catalog, el aumento del motor Node y lo que ya no se incluye.

Estado del repositorio. Esta es la línea v2 del Inspector. El desarrollo activo ocurre en v2/main (la rama develop — todos los PR de v2 la tienen como objetivo), que se fusiona en main en los lanzamientos de hitos; main es la rama predeterminada y contiene la última v2 publicada, publicada en la etiqueta npm latest. La línea heredada v1 vive en v1/main — solo correcciones de seguridad, publicada directamente desde esa rama a la etiqueta npm v1-latest (npx @modelcontextprotocol/inspector@v1-latest). Consulta AGENTS.md para conocer las convenciones de ramas/tableros.

Inicio rápido (desarrollo)

Requiere Node >=22.19.0.

npm install          # at the repo root; postinstall cascades into every client
npm run build        # web → cli → tui → launcher

Para la iteración web diaria, ejecuta Vite directamente — HMR rápido, sin necesidad de compilar el launcher:

cd clients/web && npm run dev

Los scripts impulsados por el launcher ejecutan el launcher compilado, así que compila primero:

npm run web        # prod web launcher against clients/web/dist
npm run web:dev    # web launcher in --dev mode (Vite)

v2 no es un workspace npm — cada cliente bajo clients/* mantiene su propio package.json y node_modules, y el código compartido vive en core/, consumido a través de un alias de tiempo de compilación @inspector/core. Cada dependencia de runtime que core/ importa se declara una vez, en el package.json raíz del repositorio, y cada cliente declara solo lo que ese cliente consume — su pila de UI, sus paquetes integrados por el bundler, sus herramientas de desarrollo — lo que deja a clients/cli y clients/launcher sin dependencias de runtime propias. Lo que eso significa para agregar una dependencia (raíz vs. cliente, dependencies vs. devDependencies, y las listas del bundler external) está en la habilidad local-dev.

Estructura del proyecto

inspector/
├── clients/
│   ├── web/          Web client (Vite + React + Mantine). src/ = browser app; server/ = Node backend
│   ├── cli/          CLI client (tsup bundle, @inspector/core alias)
│   ├── tui/          TUI client (Ink + React, tsup bundle)
│   └── launcher/     Shared launcher — provides the `mcp-inspector` bin, dispatches to web/cli/tui
├── core/             Shared code consumed via the `@inspector/core` alias (no package.json)
├── test-servers/     Composable MCP test servers + fixtures used by integration and smoke tests
├── scripts/          Root build/verify tooling (install cascade, smokes, the verify:* guards),
│                     repo automation run from CI (the dependency, Dependabot-alert and SDK sweeps)
│                     and the Docker image's HEALTHCHECK probe
├── docs/             Task-oriented guides — see below
├── specification/    Design/build specifications
├── .claude/skills/   Agent skills: the repo's procedures, invokable by name
├── AGENTS.md         Contribution rules for agents AND humans
└── README.md         You are here

Cada cliente tiene su propio README con detalles específicos del cliente: web · cli · tui · launcher.

Documentación

GuíaCubre
ArquitecturaEl paquete compartido @inspector/core y el enfoque de "componentes tontos" + Storybook del cliente web
Pruebas y el control de calidadQué cubre cada script validate / coverage / smoke / verify:*, la división GitHub-CI vs. gate local y los navegadores compatibles
Escribir una habilidadCómo escribir una descripción de habilidad que realmente se active, y casos de evaluación que la midan — las formas de caso que funcionan y el bucle de ajuste
Servidores de pruebaLos servidores de prueba componibles y la configuración de demostración para cada característica — qué ejecutar, qué hacer clic y qué hizo la compilación rota
PublicaciónQué se incluye en el tarball, las invariantes de empaquetado y pack:verify
DockerEjecutar la imagen del contenedor — puertos, volúmenes y hacer que los secretos sean duraderos en un contenedor
Dónde se almacenan los secretosCómo se elige el almacén de secretos en cada runtime — llavero del sistema operativo, secrets.json o memoria — además del cifrado de archivos, bloqueo y regreso a un llavero
Migración de v1 a v2Mapeo de banderas de CLI, --config vs. --catalog, el aumento del motor Node, renombres de variables de entorno
Variables de entornoCada variable que cambia el comportamiento del runtime — autenticación, puertos, almacenamiento, el almacén de secretos, registro, proxies — además de las variables TLS de Node para un servidor autofirmado
Configuración del servidor MCPA qué servidor(es) se conecta el Inspector y el formato del archivo de configuración
Revisión de una App MCPLa receta CLI-primero → web de una sola vez para la revisión automatizada de herramientas de App
Pruebas de humo de un servidor MCPEl flujo de trabajo conectar → listar → llamar → afirmar para un trabajo de shell o CI: --format json + jq, el mapa de códigos de salida y mantener OAuth no interactivo
Consolidación del launcher y la configuraciónPor qué el launcher ejecuta un cliente en proceso en lugar de generarlo
Hoja de ruta, agosto 2026 → febrero 2027El plan de seis meses: trabajo de seguimiento de especificaciones alineado con la hoja de ruta publicada de MCP, soporte oficial de extensiones y el trabajo de experiencia que elegimos
MCP Inspector: Nuestra fábrica de software de IACómo ocurren realmente las contribuciones desde v2.0.0 — trabajo impulsado por problemas de principio a fin, la división reglas/habilidades, los barridos que reemplazaron a Dependabot, el control de calidad y hacia dónde se dirige

Pruebas y el control de calidad

Cada cliente se autovalida desde su propia carpeta; los scripts raíz los encadenan. No hay un script agregado raíz test.

npm run validate     # fast inner loop: format:check + lint + typecheck + build + unit tests
npm run coverage     # the per-file ≥90% gate (lines/statements/functions/branches)
npm run local:gate   # MANDATORY before pushing — every GitHub CI check, plus one local-only one

npm run local:gate encadena cada verificación a continuación, además de las pruebas de humo y las pruebas de Storybook. Pruebas y el control de calidad posee la lista de etapas y dice qué cubre cada una y por qué una es solo local; AGENTS.md contiene las reglas de prueba en sí.

Contribuir — AGENTS.md, CLAUDE.md y las habilidades

AGENTS.md es el contrato para cambiar este código base, y se aplica tanto a humanos como a agentes de IA por igual. No es un boilerplate solo para agentes — contiene las reglas reales del proyecto: las convenciones de versión/etiqueta, los estándares de TypeScript y Mantine/React, los requisitos de prueba y cobertura, y el gate obligatorio previo al push. Léelo antes de hacer cambios y mantenlo actualizado cuando cambies estructura, herramientas o reglas.

Los procedimientos del repositorio — recetas de varios pasos con comandos e IDs en vivo — viven en .claude/skills/ en su lugar, un directorio por procedimiento, para que se carguen solo cuando la tarea los requiera. Son Markdown ordinario confirmado: un agente que no entiende habilidades puede leerlos, y AGENTS.md lleva un índice de lo que existe. Los usuarios de Claude Code los invocan por nombre (/release, /issue-triage, …).

CLAUDE.md es el punto de entrada que Claude Code carga automáticamente; incluye AGENTS.md, para que agentes y humanos trabajen desde la misma fuente de verdad. Si usas un agente diferente que lee AGENTS.md, obtienes las mismas reglas.

Una regla clave que vale la pena destacar aquí: todo el trabajo está impulsado por problemas. Antes de comenzar, encuentra o crea un problema de seguimiento en el tablero del proyecto v2; abre PRs contra v2/main con Closes #<issue>. Las contribuciones externas se aceptan como problemas, no pull requests — consulta CONTRIBUTING.md.

Licencia

Consulta LICENSE. El proyecto MCP está en transición de la Licencia MIT a Apache-2.0: las nuevas contribuciones de código están licenciadas bajo Apache-2.0, la documentación (excluyendo especificaciones) bajo CC-BY-4.0, y las contribuciones cuyos autores las licenciaron originalmente bajo MIT y no han otorgado consentimiento de relicenciamiento permanecen bajo MIT. El archivo contiene los textos completos de Apache-2.0 y MIT y enlaza el código legal de CC-BY-4.0.