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

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

### 2. Install Globally from NPM

Install the package globally using npm.

**Installation:**

```bash
npm install -g mcp-insomnia
```

**Configuration:**

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

### 3. Install from Source

Clone the repository and build the project.

**Installation:**

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

**Configuration:**

```json
{
  "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](#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](#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:

| Parameter | `execute_request` | `execute_insomnia_request` | Description |
|-----------|:-:|:-:|-------------|
| `requestId` | ✓ | ✓ | ID of the request to run |
| `environmentId` | ✓ | ✓ | Sub-environment ID for variable substitution |
| `overrideVariables` | ✓ | ✓ | Per-call variable overrides (e.g. `{"token": "abc123"}`) |
| `environmentVariables` | ✓ | | Legacy final override layer for MCP collections |
| `timeoutMs` | ✓ | ✓ | Request timeout in ms (default `30000`; set `<= 0` for no timeout — MCP cancellation still applies) |
| `maxResponseBytes` | ✓ | | Max serialized response body size in tool output; exceeded bodies are truncated to a preview |

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

```json
{
  "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.

```bash
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](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, etc.).

Found a bug or have an idea? [Open an issue](https://github.com/anggasct/mcp-insomnia/issues).

## License

[MIT License](LICENSE)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.