Postman API V3

Servidor MCP para la API de Postman v3

Documentación

Servidor MCP de Postman

Versión: v0.2.0

Un servidor MCP que proporciona acceso a la API de Postman. La funcionalidad se basa en la especificación oficial de OpenAPI. Para más información, consulta la documentación de la API de Postman.

Este proyecto forma parte de la iniciativa Model Context Protocol (MCP) de Anthropic. Para más información, visita el repositorio de MCP en GitHub y el anuncio en el blog de Anthropic.

Ir directamente a las instrucciones de instalación

postman-mcp-server - Cover Image

[!ADVERTENCIA] Este proyecto se encuentra actualmente en desarrollo activo. Por favor, úsalo con precaución y espera cambios importantes.

[!NOTA] Código generado por IA. Utilicé Cline v2.2.2 con Claude 3.5 Sonnet (2024-10-22). Consulta docs/README.md para ver las indicaciones y los detalles sobre cómo se generó este código.

Descripción general
Características
Instalación
- Requisitos previos
- Pasos
Uso
Documentación
- Descripción general del proyecto
Justificación
Desarrollo
Depuración
Otros servidores MCP
Licencia

Descripción general

Postman MCP Server es un servidor MCP basado en TypeScript que se integra con la API de Postman, proporcionando una gestión integral de colecciones, entornos y APIs de Postman.

Características

Colecciones

Operaciones CRUD: Crear, recuperar y actualizar colecciones de Postman.
Gestión de carpetas: Organizar solicitudes en carpetas dentro de las colecciones.
Gestión de solicitudes: Añadir y actualizar solicitudes dentro de las colecciones.
Gestión de respuestas: Gestionar las respuestas asociadas a las solicitudes.
Control de versiones: Bifurcar, fusionar y extraer cambios de las colecciones.
Comentarios: Añadir y gestionar comentarios en las colecciones.

Entornos

Gestión de entornos: Crear y recuperar entornos para diferentes configuraciones.
Operaciones CRUD: Soporte completo para crear, actualizar y eliminar entornos.

APIs

Gestión de APIs: Crear, recuperar, actualizar y eliminar APIs.
Soporte de esquemas: Gestionar esquemas de API con soporte de múltiples archivos.
Etiquetado: Añadir y gestionar etiquetas para las APIs.
Comentarios: Añadir y gestionar comentarios en las APIs.

Autenticación y autorización

Autenticación con clave de API: Acceso seguro mediante claves de API.
Control de acceso basado en roles: Gestionar permisos a nivel de espacio de trabajo y colección.
Permisos de espacio de trabajo: Definir permisos específicos para los espacios de trabajo.

Características adicionales

Red de API privada: Gestionar elementos y carpetas dentro de una red de API privada.
Webhooks: Crear webhooks para activar colecciones con cargas útiles personalizadas.
Características empresariales: Controles de roles avanzados y soporte SCIM para entornos empresariales.

Instalación

Instalación mediante npm (recomendada)

Instala el paquete globalmente:

npm install -g @postmanv3/postman-mcp-server

O instálalo localmente en tu proyecto:

npm install @postmanv3/postman-mcp-server

Instalación mediante Smithery

Para instalar Postman MCP Server para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install postman-api-server --client claude

Instalación desde el código fuente

Si prefieres compilar desde el código fuente:

Clonar el repositorio:

git clone https://github.com/PostmanV3/postman-mcp-server.git
cd postman-mcp-server

Instalar las dependencias:
```
npm install
# or
pnpm install
```
Compilar el servidor:
```
npm run build
# or
pnpm run build
```
Ejecutar en modo de desarrollo con recompilación automática:
```
npm run watch
# or
pnpm run watch
```

Uso

Configuración de claves de API

Genera tu clave de API
- Visita Configuración de la cuenta de Postman
- Haz clic en "Generar clave de API"
- Guarda la clave de forma segura: no se volverá a mostrar
Configura la clave de API
- Añade la clave a tu entorno como POSTMAN_API_KEY
- Para Claude Desktop o Cline, inclúyela en tu archivo de configuración (consulta los ejemplos de configuración a continuación)
- Nunca subas claves de API al control de versiones
Verifica el acceso
- La clave de API proporciona acceso a todos los recursos de Postman para los que tengas permisos
- Prueba el acceso ejecutando una consulta simple (por ejemplo, listar espacios de trabajo)

[!NOTA] Si estás utilizando la colección de la API de Postman directamente, guarda tu clave de API como una variable de colección postman-api-key.

Uso con Claude Desktop

Para usar con Claude Desktop, añade la configuración del servidor:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

[!IMPORTANTE] Si estás actualizando este proveedor, Claude debe reiniciarse para que se apliquen los cambios de API del esquema de entrada (es decir, cuando los elementos ToolDefinition del servidor MCP hayan cambiado). Esto se debe a que Claude almacena en caché las definiciones de herramientas al iniciarse.

Ejemplo de configuración

Recomendado: Usar npx (funciona tanto con instalaciones globales como locales):

{
  "mcpServers": {
    "postman": {
      "command": "npx",
      "args": [
        "-y",
        "@postmanv3/postman-mcp-server"
      ],
      "env": {
        "POSTMAN_API_KEY": "CHANGEME"
      }
    }
  }
}

Alternativa: Ruta directa (si está instalado localmente):

{
  "mcpServers": {
    "postman": {
      "command": "node",
      "args": [
        "./node_modules/@postmanv3/postman-mcp-server/build/index.js"
      ],
      "env": {
        "POSTMAN_API_KEY": "CHANGEME"
      }
    }
  }
}

Alternativa: Ruta de instalación global (rutas típicas: encuentra la tuya con npm root -g):

{
  "mcpServers": {
    "postman": {
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/@postmanv3/postman-mcp-server/build/index.js"
      ],
      "env": {
        "POSTMAN_API_KEY": "CHANGEME"
      }
    }
  }
}

[!NOTA] Para encontrar la ruta de tu node_modules global, ejecuta npm root -g y reemplaza la ruta anterior en consecuencia.

[!CONSEJO] Se recomienda el enfoque npx, ya que encuentra automáticamente el paquete tanto si está instalado globalmente como localmente, y gestiona las actualizaciones automáticamente.

Uso con Cline

Usando la misma configuración de ejemplo, añade la configuración del servidor a tu configuración de servidores MCP de Cline:

Ejemplo de configuración

Igual que con Claude arriba.

Uso con Zed

Todavía estoy intentando que esto funcione. Según la documentación de Zed, parece que necesita ser una extensión (también este problema #21455).

Documentación

La documentación oficial de la API de Postman está disponible en el Espacio de trabajo público de Postman.

Descripción general del proyecto

Referencias y resúmenes de la API de Postman

Este proyecto aprovecha el modelo Claude y la extensión Cline para convertir la especificación OpenAPI en código TypeScript, mejorando la seguridad de tipos y la integración dentro del servidor MCP.

Este proyecto de GitHub incluye documentación de referencias de API que proporciona una guía detallada sobre cómo utilizar la plataforma Postman mediante programación. Cubre tanto el SDK de Collection para el desarrollo local como la API de Postman para la integración con la plataforma en la nube. Los temas clave incluyen mecanismos de autenticación, límites de velocidad y documentación detallada de todos los endpoints de la API, incluidos espacios de trabajo, colecciones, entornos y más. Además, la guía ofrece requisitos previos e instrucciones de inicio rápido para facilitar interacciones fluidas con la API.

El directorio docs/api/summaries contiene resúmenes completos en Markdown de la API de Postman. Estos documentos describen los endpoints de la API, los formatos de solicitud/respuesta y los detalles de implementación esenciales para validar y garantizar la funcionalidad del servidor MCP. Consulta el README de resúmenes de API para obtener una descripción general de la estructura de la documentación y las estrategias de implementación.

Conversión de la especificación OpenAPI a código TypeScript con Claude

Creación del servidor MCP

Consulta la documentación de handlers para obtener especificaciones detalladas sobre la implementación de handlers del servidor MCP. Esto incluye formatos de URI, requisitos de prompts y patrones de gestión de recursos. Esta guía es crucial para los desarrolladores que trabajan en la integración y mejora de las funcionalidades de la API de Postman dentro del servidor MCP.

Justificación

El wrapper MCP para las herramientas de Postman tiene sentido principalmente como una capa de interacción de IA para operaciones complejas y de múltiples pasos donde la estructura y la seguridad son primordiales. Sin embargo, puede estar sobrediseñado para operaciones simples donde el uso directo de CLI o API sería suficiente. El wrapper MCP proporciona el mayor valor cuando:

Operaciones complejas

Gestión de múltiples colecciones
Coordinación de entornos
Generación de informes completos

Automatización impulsada por IA

Flujos de trabajo de pruebas automatizadas
Mantenimiento de documentación de API
Gestión de entornos

Operaciones sensibles a errores

Pruebas críticas de API
Despliegues en producción
Verificación de cumplimiento

Proporciona menos valor para:

Operaciones simples

Ejecuciones básicas de colecciones
Llamadas individuales a la API
Comprobaciones rápidas de entornos

Uso directo de CLI

Operaciones impulsadas por desarrolladores
Pruebas locales
Iteraciones rápidas

Desarrollo

Instala las dependencias:

npm install
# or
pnpm install

Compila el servidor:

npm run build
# or
pnpm run build

Para desarrollo con recompilación automática:

npm run watch
# or
pnpm run watch

Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser un desafío. Recomendamos usar el Inspector MCP, disponible como script de paquete:

npm run inspector
# or
pnpm run inspector

Documentación

El Inspector proporcionará una URL para acceder a las herramientas de depuración en tu navegador: http://localhost:5173. Deberás añadir la POSTMAN_API_KEY antes de conectarte. Navega a "Tools" para comenzar.

Otros servidores MCP

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENCIA para más detalles.

Este servidor MCP es solo para fines de investigación. Cualquier recopilación de datos o monitoreo se realizará únicamente con fines de investigación de seguridad.