MCP-Insomnia

Um servidor MCP para agentes de IA criarem e gerenciarem coleções de API no formato compatível com Insomnia.

GitHub
25
Experimente este MCPPatrocinado

Documentação

MCP-Insomnia

MCP-Insomnia é um servidor MCP (Model Context Protocol) que permite que agentes de IA criem e gerenciem coleções de API em formato compatível com o Insomnia. Este servidor fornece ferramentas para gerenciar coleções, requisições e ambientes que podem ser exportados para o Insomnia.

Instalação e Uso

Pré-requisitos

  • Node.js 18+
  • npm ou yarn

Existem três maneiras de usar o mcp-insomnia.

1. Executar com NPX (Recomendado)

Você pode executar o mcp-insomnia diretamente usando o npx sem instalação global.

Configuração:

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

2. Instalar Globalmente via NPM

Instale o pacote globalmente usando npm.

Instalação:

npm install -g mcp-insomnia

Configuração:

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

3. Instalar a partir do Código-Fonte

Clone o repositório e compile o projeto.

Instalação:

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

Configuração:

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

Ferramentas Disponíveis

Gerenciamento de Coleções

  • create_collection - Criar nova coleção/workspace
  • list_collections - Listar todas as coleções
  • get_collection_detail - Obter detalhes completos e estatísticas de uma coleção
  • export_collection - Exportar coleção para formato JSON

Gerenciamento de Pastas

  • create_folder - Criar pasta dentro da coleção

Gerenciamento de Requisições

  • list_requests - Listar todas as requisições, opcionalmente filtrar por coleção
  • get_request - Obter detalhes completos de uma requisição específica
  • create_request_in_collection - Criar nova requisição
  • update_request - Atualizar requisição existente
  • delete_request - Excluir requisição
  • execute_request - Executar uma requisição armazenada no MCP e retornar a resposta (suporta resolução de ambiente, timeouts e limites de tamanho de resposta — veja Execução de requisições)
  • get_request_history - Obter histórico de execução de uma requisição (até 20 entradas por requisição)

Ferramentas de Importação

  • import_from_curl - Analisar comando cURL em uma requisição
  • import_from_postman - Importar Postman Collection (v2.1) JSON
  • import_from_openapi - Importar OpenAPI 3.x ou Swagger 2.x JSON
  • import_from_insomnia_export - Importar coleções de um arquivo de exportação padrão do Insomnia V4

Ferramentas Utilitárias

  • generate_code_snippet - Gerar um snippet de código para uma requisição. Requer requestId e target. Alvos suportados: c, clojure, csharp, go, http, java, javascript, kotlin, node, objc, ocaml, php, powershell, python, ruby, shell, swift. O client opcional seleciona uma biblioteca (ex.: axios para javascript, curl para shell).

Integração Direta com o Insomnia (NeDB)

Interaja diretamente com o banco de dados local do aplicativo Insomnia (macOS, Linux, Windows).

  • list_insomnia_projects - Listar todos os projetos/equipes do Insomnia
  • list_insomnia_collections - Listar todos os workspaces/coleções do Insomnia
  • get_insomnia_collection - Obter detalhes completos de um workspace específico do Insomnia
  • get_insomnia_request - Obter detalhes completos de uma requisição específica do Insomnia
  • sync_from_insomnia - Importar um workspace do Insomnia para o MCP
  • sync_all_from_insomnia - Importar todos os workspaces do Insomnia para o MCP
  • sync_to_insomnia - Exportar uma coleção do MCP de volta para o Insomnia
  • execute_insomnia_request - Executar uma requisição diretamente do Insomnia sem sincronização (suporta resolução de ambiente e timeouts — veja Execução de requisições)

Gerenciamento de Ambientes

  • set_environment_variable - Definir variável de ambiente
  • get_environment_variables - Obter variáveis de ambiente

Ao executar requisições, as variáveis de ambiente são mescladas em camadas (camadas posteriores sobrescrevem as anteriores):

Coleções MCP (execute_request):

  1. Ambientes de workspace/base anexados à coleção
  2. Sub-ambiente (environmentId, se fornecido)
  3. Ambientes de pasta ao longo da cadeia de ancestrais da requisição
  4. overrideVariables (sobrescritas por chamada)
  5. environmentVariables (camada de sobrescrita final legada)

Aplicativo Insomnia (execute_insomnia_request):

  1. Ambiente global (nível de projeto)
  2. Ambiente base (nível de workspace)
  3. Sub-ambiente (environmentId, se fornecido)
  4. Ambientes de pasta ao longo da cadeia de ancestrais da requisição
  5. overrideVariables (sobrescritas por chamada)

Execução de requisições

Ambas as ferramentas de execução aceitam parâmetros opcionais de tempo de execução:

Parâmetroexecute_requestexecute_insomnia_requestDescrição
requestId✓✓ID da requisição a ser executada
environmentId✓✓ID do sub-ambiente para substituição de variáveis
overrideVariables✓✓Sobrescritas de variáveis por chamada (ex.: {"token": "abc123"})
environmentVariables✓Camada de sobrescrita final legada para coleções MCP
timeoutMs✓✓Timeout da requisição em ms (padrão 30000; defina <= 0 para sem timeout — o cancelamento do MCP ainda se aplica)
maxResponseBytes✓Tamanho máximo do corpo de resposta serializado na saída da ferramenta; corpos excedentes são truncados para uma prévia

Busca e Estatísticas

  • search - Buscar em todas as coleções, pastas e requisições
  • get_stats - Obter estatísticas globais de todas as coleções

Exemplos de Uso

Criar Coleção

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

Adicionar Requisição

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

Definir Variável de Ambiente

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

Executar Requisição

Execute "Get Users" request using the configured environment variables

Com parâmetros opcionais:

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

Gerar Snippet de Código

Generate a code snippet for request req_abc123 in javascript using axios

Armazenamento de Dados

Os dados são armazenados em dois locais:

  1. Armazenamento MCP: ~/.mcp-insomnia/collections.json

    • Área de trabalho para criar/editar coleções antes da sincronização
    • Alterações aqui NÃO afetam o aplicativo Insomnia até a sincronização
    • Ideal para gerar novas coleções, importar do OpenAPI ou refatoração em massa

  2. Armazenamento do Aplicativo Insomnia (NeDB)

    • O banco de dados usado pelo aplicativo Insomnia
    • Alterações aqui são visíveis no aplicativo (pode exigir reinicialização)
    • Caminhos padrão:
      • macOS: ~/Library/Application Support/Insomnia
      • Linux: ~/.config/Insomnia
      • Linux (Flatpak): ~/.var/app/rest.insomnia.Insomnia/config/Insomnia
      • Windows: %APPDATA%/Insomnia

Diretório de Dados Personalizado do Insomnia

Se o Insomnia estiver instalado em um local não padrão, você pode definir a variável de ambiente INSOMNIA_DATA_DIR para especificar o caminho:

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

Nota: Instalações Flatpak no Linux são detectadas automaticamente — você só precisa do INSOMNIA_DATA_DIR se seus dados do Insomnia estiverem em um local verdadeiramente personalizado.

Fluxo de Trabalho Recomendado

Cenário A: Criando/Modificando Conteúdo

  1. Importar/Buscar: Obter dados do Insomnia (sync_from_insomnia ou import_from_openapi)
  2. Editar: Modificar requisições/pastas usando ferramentas MCP (create_request_in_collection, update_request)
  3. Publicar: Sincronizar alterações de volta para o Insomnia (sync_to_insomnia)

Cenário B: Executando Requisições Existentes

  • Use execute_insomnia_request para executar requisições diretamente do aplicativo Insomnia sem sincronização

Contribuindo

Contribuições são bem-vindas! Correções de bugs, novas ferramentas e melhorias são 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

Faça um fork do repositório, crie uma branch a partir de main e abra um PR. Use conventional commits (feat:, fix:, docs:, etc.).

Encontrou um bug ou tem uma ideia? Abra uma issue.

Licença

Licença MIT

Changelog

Consulte CHANGELOG.md para o histórico de versões.