npm package: @iflow-mcp/anggasct-mcp-insomnia
Description: MCP server for making HTTP requests and managing API collections
Author: angga permana
Latest version: 0.4.0

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

```json
{
  "mcpServers": {
    "insomnia": {
      "command": "npx",
      "args": ["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
- `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

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

### Generate Code Snippet

```
Generate a code snippet for Insomnia request "Get Users" in "javascript"
```

## 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](LICENSE)

## Changelog

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