MCP-Insomnia

MCP-Insomnia is an MCP (Model Context Protocol) server that enables AI agents to create and manage API collections in Insomnia-compatible format. This server provides tools and resources for managing collections, requests, and environments that can be exported to Insomnia.

Installation and Usage

Prerequisites

• Node.js 18+

• npm or yarn

There are three ways to use mcp-insomnia.

1. Run with NPX (Recommended)

You can run mcp-insomnia directly using npx without a global installation.

Configuration:

2. Install Globally from NPM

Install the package globally using npm.

Installation:

Configuration:

3. Install from Source

Clone the repository and build the project.

Installation:

Configuration:

Available Tools

Collection Management

• create_collection - Create new collection/workspace

• list_collections - List all collections

• export_collection - Export collection to JSON format

Folder Management

• create_folder - Create folder within collection

Request Management

• create_request_in_collection - Create new request

• update_request - Update existing request

• delete_request - Delete request

• execute_request - Execute request and view response

• generate_code_snippet - Generate a code snippet for a request in various languages/frameworks

Import Tools

• import_from_curl - Parse cURL command into a request

• import_from_postman - Import Postman Collection (v2.1) JSON

• import_from_openapi - Import OpenAPI/Swagger (v3.0) JSON

• import_from_insomnia_export - Import collections from a standard Insomnia V4 export file

Insomnia Direct Integration (NeDB)

Interact directly with the local Insomnia application database (macOS).

• list_insomnia_projects - List all projects/teams from Insomnia

• list_insomnia_collections - List all workspaces/collections from Insomnia

• get_insomnia_collection - Get full details of a specific Insomnia workspace

• get_insomnia_request - Get full details of a specific Insomnia request

• sync_from_insomnia - Import a workspace from Insomnia to MCP

• sync_all_from_insomnia - Import all workspaces from Insomnia to MCP

• sync_to_insomnia - Export an MCP collection back to Insomnia

• execute_insomnia_request - Execute a request directly from Insomnia (with env support)

Environment Management

• set_environment_variable - Set environment variable

• get_environment_variables - Get environment variables

Available Resources

• insomnia://collections - List all collections

• insomnia://requests - List all requests. Can be filtered by ?collectionId={id}.

• insomnia://environments - List environment variables. Can be filtered by ?collectionId={id}.

• insomnia://collection/{id} - Specific collection details

• insomnia://request/{id} - Specific request details

• insomnia://request/{id}/history - Get the execution history for a specific request

• insomnia://search?q={keyword} - Search across all collections, folders, and requests.

• insomnia://stats - Global statistics

Usage Examples

Create Collection

Add Request

Set Environment Variable

Execute Request

Generate Code Snippet

Data Storage

Data is stored in two locations:

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

   • Working area for building/editing collections before syncing

   • Changes here do NOT affect the Insomnia App until synced

   • Ideal for generating new collections, importing from OpenAPI, or mass-refactoring

2. Insomnia App Storage: ~/Library/Application Support/Insomnia (NeDB)

   • The database used by Insomnia App

   • Changes here are visible in the App (may require restart)

Recommended Workflow

Scenario A: Creating/Modifying Content

1. Import/Fetch: Pull data from Insomnia (sync_from_insomnia or import_from_openapi)

2. Edit: Modify requests/folders using MCP tools (create_request, update_request)

3. Publish: Sync changes back to Insomnia (sync_to_insomnia)

Scenario B: Running Existing Requests

• Use execute_insomnia_request to run requests directly from Insomnia App without syncing

License

MIT License

Changelog

See CHANGELOG.md for release history.