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 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:

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

2. Install Globally from NPM

Install the package globally using npm.

Installation:

npm install -g mcp-insomnia

Configuration:

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

3. Install from Source

Clone the repository and build the project.

Installation:

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

Configuration:

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

Available Tools

Collection Management

• create_collection - Create new collection/workspace

• list_collections - List all collections

• get_collection_detail - Get full details and statistics of a collection

• export_collection - Export collection to JSON format

Folder Management

• create_folder - Create folder within collection

Request Management

• list_requests - List all requests, optionally filter by collection

• get_request - Get full details of a specific request

• create_request_in_collection - Create new request

• update_request - Update existing request

• delete_request - Delete request

• execute_request - Execute an MCP-stored request and return the response (supports environment resolution, timeouts, and response size limits — see Request execution)

• get_request_history - Get execution history of a request (up to 20 entries per request)

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 3.x or Swagger 2.x JSON

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

Utility Tools

• generate_code_snippet - Generate a code snippet for a request. Requires requestId and target. Supported targets: c, clojure, csharp, go, http, java, javascript, kotlin, node, objc, ocaml, php, powershell, python, ruby, shell, swift. Optional client selects a library (e.g. axios for javascript, curl for shell).

Insomnia Direct Integration (NeDB)

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

• 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 without syncing (supports environment resolution and timeouts — see Request execution)

Environment Management

• set_environment_variable - Set environment variable

• get_environment_variables - Get environment variables

When executing requests, environment variables are merged in layers (later layers override earlier ones):

MCP collections (execute_request):

1. Workspace/base environments attached to the collection

2. Sub-environment (environmentId, if provided)

3. Folder environments along the request's ancestor chain

4. overrideVariables (per-call overrides)

5. environmentVariables (legacy final override layer)

Insomnia app (execute_insomnia_request):

1. Global environment (project level)

2. Base environment (workspace level)

3. Sub-environment (environmentId, if provided)

4. Folder environments along the request's ancestor chain

5. overrideVariables (per-call overrides)

Request execution

Both execution tools accept optional runtime parameters:

Search & Statistics

• search - Search across all collections, folders, and requests

• get_stats - Get global statistics of all collections

Usage Examples

Create Collection

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

Add Request

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

Set Environment Variable

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

Execute Request

Execute "Get Users" request using the configured environment variables

With optional parameters:

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

Generate Code Snippet

Generate a code snippet for request req_abc123 in javascript using axios

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 (NeDB)

   • The database used by Insomnia App

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

   • Default paths:

     • macOS: ~/Library/Application Support/Insomnia

     • Linux: ~/.config/Insomnia

     • Linux (Flatpak): ~/.var/app/rest.insomnia.Insomnia/config/Insomnia

     • Windows: %APPDATA%/Insomnia

Custom Insomnia Data Directory

If Insomnia is installed in a non-default location, you can set the INSOMNIA_DATA_DIR environment variable to specify the path:

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

Note: Flatpak installations on Linux are auto-detected — you only need INSOMNIA_DATA_DIR if your Insomnia data is in a truly custom location.

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_in_collection, 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

Contributing

Contributions are welcome! Bug fixes, new tools, and improvements are all appreciated.

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

Fork the repo, create a branch from main, and open a PR. Use conventional commits (feat:, fix:, docs:, etc.).

Found a bug or have an idea? Open an issue.

License

MIT License

Changelog

See CHANGELOG.md for release history.