MCP-Insomnia

Un servidor MCP para que agentes de IA creen y gestionen colecciones de API en formato compatible con Insomnia.

Documentación

MCP-Insomnia

MCP-Insomnia es un servidor MCP (Model Context Protocol) que permite a los agentes de IA crear y gestionar colecciones de API en formato compatible con Insomnia. Este servidor proporciona herramientas para gestionar colecciones, solicitudes y entornos que pueden exportarse a Insomnia.

Instalación y Uso

Requisitos previos

Node.js 18+
npm o yarn

Hay tres formas de usar mcp-insomnia.

1. Ejecutar con NPX (Recomendado)

Puedes ejecutar mcp-insomnia directamente usando npx sin instalación global.

Configuración:

{
  "mcpServers": {
    "insomnia": {
      "command": "npx",
      "args": ["-y", "mcp-insomnia"]
    }
  }
}

2. Instalar Globalmente desde NPM

Instala el paquete globalmente usando npm.

Instalación:

npm install -g mcp-insomnia

Configuración:

{
  "mcpServers": {
    "insomnia": {
      "command": "mcp-insomnia"
    }
  }
}

3. Instalar desde el Código Fuente

Clona el repositorio y compila el proyecto.

Instalación:

git clone https://github.com/anggasct/mcp-insomnia.git
cd mcp-insomnia
npm install
npm run build

Configuración:

{
  "mcpServers": {
    "insomnia": {
      "command": "node",
      "args": ["/path/to/mcp-insomnia/dist/index.js"]
    }
  }
}

Herramientas Disponibles

Gestión de Colecciones

create_collection - Crear nueva colección/espacio de trabajo
list_collections - Listar todas las colecciones
get_collection_detail - Obtener detalles completos y estadísticas de una colección
export_collection - Exportar colección a formato JSON

Gestión de Carpetas

create_folder - Crear carpeta dentro de la colección

Gestión de Solicitudes

list_requests - Listar todas las solicitudes, opcionalmente filtrar por colección
get_request - Obtener detalles completos de una solicitud específica
create_request_in_collection - Crear nueva solicitud
update_request - Actualizar solicitud existente
delete_request - Eliminar solicitud
execute_request - Ejecutar una solicitud almacenada en MCP y devolver la respuesta (admite resolución de entornos, tiempos de espera y límites de tamaño de respuesta — ver Ejecución de solicitudes)
get_request_history - Obtener historial de ejecución de una solicitud (hasta 20 entradas por solicitud)

Herramientas de Importación

import_from_curl - Analizar comando cURL en una solicitud
import_from_postman - Importar colección de Postman (v2.1) JSON
import_from_openapi - Importar OpenAPI 3.x o Swagger 2.x JSON
import_from_insomnia_export - Importar colecciones desde un archivo de exportación estándar de Insomnia V4

Herramientas de Utilidad

generate_code_snippet - Generar un fragmento de código para una solicitud. Requiere requestId y target. Destinos compatibles: c, clojure, csharp, go, http, java, javascript, kotlin, node, objc, ocaml, php, powershell, python, ruby, shell, swift. client opcional selecciona una librería (p. ej. axios para javascript, curl para shell).

Integración Directa con Insomnia (NeDB)

Interactúa directamente con la base de datos local de la aplicación Insomnia (macOS, Linux, Windows).

list_insomnia_projects - Listar todos los proyectos/equipos de Insomnia
list_insomnia_collections - Listar todos los espacios de trabajo/colecciones de Insomnia
get_insomnia_collection - Obtener detalles completos de un espacio de trabajo específico de Insomnia
get_insomnia_request - Obtener detalles completos de una solicitud específica de Insomnia
sync_from_insomnia - Importar un espacio de trabajo de Insomnia a MCP
sync_all_from_insomnia - Importar todos los espacios de trabajo de Insomnia a MCP
sync_to_insomnia - Exportar una colección de MCP de vuelta a Insomnia
execute_insomnia_request - Ejecutar una solicitud directamente desde Insomnia sin sincronizar (admite resolución de entornos y tiempos de espera — ver Ejecución de solicitudes)

Gestión de Entornos

set_environment_variable - Establecer variable de entorno
get_environment_variables - Obtener variables de entorno

Al ejecutar solicitudes, las variables de entorno se fusionan en capas (las capas posteriores anulan a las anteriores):

Colecciones MCP (execute_request):

Entornos base/espacio de trabajo adjuntos a la colección
Sub-entorno (environmentId, si se proporciona)
Entornos de carpeta a lo largo de la cadena de ancestros de la solicitud
overrideVariables (anulaciones por llamada)
environmentVariables (capa de anulación final heredada)

Aplicación Insomnia (execute_insomnia_request):

Entorno global (nivel de proyecto)
Entorno base (nivel de espacio de trabajo)
Sub-entorno (environmentId, si se proporciona)
Entornos de carpeta a lo largo de la cadena de ancestros de la solicitud
overrideVariables (anulaciones por llamada)

Ejecución de Solicitudes

Ambas herramientas de ejecución aceptan parámetros de tiempo de ejecución opcionales:

Parámetro	`execute_request`	`execute_insomnia_request`	Descripción
`requestId`	✓	✓	ID de la solicitud a ejecutar
`environmentId`	✓	✓	ID del sub-entorno para sustitución de variables
`overrideVariables`	✓	✓	Anulaciones de variables por llamada (p. ej. `{"token": "abc123"}`)
`environmentVariables`	✓		Capa de anulación final heredada para colecciones MCP
`timeoutMs`	✓	✓	Tiempo de espera de la solicitud en ms (predeterminado `30000`; establece `<= 0` para sin tiempo de espera — la cancelación de MCP sigue aplicándose)
`maxResponseBytes`	✓		Tamaño máximo del cuerpo de respuesta serializado en la salida de la herramienta; los cuerpos que excedan se truncan a una vista previa

Búsqueda y Estadísticas

search - Buscar en todas las colecciones, carpetas y solicitudes
get_stats - Obtener estadísticas globales de todas las colecciones

Ejemplos de Uso

Crear Colección

Create a new Insomnia collection named "API Testing" for testing endpoints

Añadir Solicitud

Add GET request to "API Testing" Insomnia collection with:
- Name: Get Users
- URL: https://jsonplaceholder.typicode.com/users
- Headers: Content-Type: application/json

Establecer Variable de Entorno

Set Insomnia environment variable "baseUrl" with value "https://api.example.com" for "API Testing" collection

Ejecutar Solicitud

Execute "Get Users" request using the configured environment variables

Con parámetros opcionales:

Execute request req_abc123 with environmentId env_xyz, timeout 15000ms, and override baseUrl to https://staging.api.example.com

Generar Fragmento de Código

Generate a code snippet for request req_abc123 in javascript using axios

Almacenamiento de Datos

Los datos se almacenan en dos ubicaciones:

Almacenamiento MCP: ~/.mcp-insomnia/collections.json
- Área de trabajo para crear/editar colecciones antes de sincronizar
- Los cambios aquí NO afectan a la aplicación Insomnia hasta que se sincronizan
- Ideal para generar nuevas colecciones, importar desde OpenAPI o refactorización masiva
Almacenamiento de la Aplicación Insomnia (NeDB)
- La base de datos utilizada por la aplicación Insomnia
- Los cambios aquí son visibles en la aplicación (puede requerir reinicio)
- Rutas predeterminadas:
  - macOS: ~/Library/Application Support/Insomnia
  - Linux: ~/.config/Insomnia
  - Linux (Flatpak): ~/.var/app/rest.insomnia.Insomnia/config/Insomnia
  - Windows: %APPDATA%/Insomnia

Directorio de Datos Personalizado de Insomnia

Si Insomnia está instalado en una ubicación no predeterminada, puedes establecer la variable de entorno INSOMNIA_DATA_DIR para especificar la ruta:

{
  "mcpServers": {
    "insomnia": {
      "command": "npx",
      "args": ["mcp-insomnia"],
      "env": {
        "INSOMNIA_DATA_DIR": "~/.var/app/rest.insomnia.Insomnia/config/Insomnia"
      }
    }
  }
}

Nota: Las instalaciones Flatpak en Linux se detectan automáticamente — solo necesitas INSOMNIA_DATA_DIR si tus datos de Insomnia están en una ubicación realmente personalizada.

Flujo de Trabajo Recomendado

Escenario A: Crear/Modificar Contenido

Importar/Obtener: Extraer datos de Insomnia (sync_from_insomnia o import_from_openapi)
Editar: Modificar solicitudes/carpetas usando herramientas MCP (create_request_in_collection, update_request)
Publicar: Sincronizar cambios de vuelta a Insomnia (sync_to_insomnia)

Escenario B: Ejecutar Solicitudes Existentes

Usa execute_insomnia_request para ejecutar solicitudes directamente desde la aplicación Insomnia sin sincronizar

Contribuciones

¡Las contribuciones son bienvenidas! Las correcciones de errores, nuevas herramientas y mejoras son todas apreciadas.

git clone https://github.com/anggasct/mcp-insomnia.git
cd mcp-insomnia
npm install
npm run build
npx @modelcontextprotocol/inspector node dist/index.js  # test via MCP Inspector

Haz un fork del repositorio, crea una rama desde main y abre un PR. Usa commits convencionales (feat:, fix:, docs:, etc.).

¿Encontraste un error o tienes una idea? Abre un issue.

Licencia

Licencia MIT

Registro de Cambios

Consulta CHANGELOG.md para el historial de versiones.