Insomnia MCP Server

Insomnia MCP Server exposes Kong Insomnia-compatible collections, folders, requests, and environments through the Model Context Protocol (MCP). It lets MCP-enabled assistants (Claude Desktop, Windsurf, Cursor, etc.) create and manage Insomnia workspaces without touching the GUI.

✨ Features

• Collection management – List and create collections with auto-persisted metadata
• Folder workflows – Create nested folders (Insomnia request groups), move them around, and delete hierarchies safely
• Request lifecycle – Create, update, and delete HTTP requests with headers, bodies, descriptions, optional folder placement, and pre/post request scripts
• Environment variables – Manage per-collection environment variables
• Auto-refresh plugin – Insomnia plugin for automatic collection syncing
• User-friendly responses – Clear, formatted success messages with action summaries
• Type-safe – Full TypeScript support with comprehensive JSDoc documentation

Quick Start - Update your MCP configuration

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

Claude code install command

claude mcp add insomnia npx insomnia-mcp@latest

Once connected, explore available tools and resources:

Collection Tools

• list_collections - List all collections
• create_collection - Create new collection
• get_collection - Get collection details

Request Tools

• create_request - Create HTTP request
• update_request - Update existing request
• delete_request - Delete request
• get_request - Get request details

Folder Tools

• create_folder - Create folder/group
• update_folder - Update folder
• delete_folder - Delete folder (cascades to children)
• get_folder - Get folder details

Environment Tools

• set_environment_variable - Set variable
• get_environment - Get all variables
• get_environment_variable - Get specific variable

📚 Documentation

• Architecture Documentation - System design, data flow, and extension points
• Examples - Real-world usage examples and workflows
• Changelog - Version history and release notes

🔧 Configuration

Configure via environment variables:

• INSOMNIA_MCP_DISABLE_HTTP_SERVER=true - Disable HTTP server (default: false)
• INSOMNIA_MCP_HTTP_PORT=3848 - HTTP server port (default: 3847)
• INSOMNIA_APP_DATA_DIR=/path/to/data - Insomnia data directory (default: auto-detected)
• INSOMNIA_MCP_PROJECT_ID=proj_custom - Project ID override (default: auto-detected)
• INSOMNIA_MCP_LOG_LEVEL=debug - Log level: error, warn, info, debug (default: info)

🔌 Insomnia Plugin

The project includes an Insomnia plugin that automatically syncs collections when MCP makes changes. No manual refresh or app restart needed!

How It Works

MCP Tool Call (via Claude) → MCP Server updates collections
                                       ↓
                    Plugin detects changes (polls every 5s)
                                       ↓
                    Auto-imports via Insomnia's native import API
                                       ↓
                           ✅ UI updates automatically

Recent Improvements (v0.0.3)

• Switched to import.uri() for better UI refresh behavior
• Auto-imports on change - no manual "Import from MCP" action needed
• Graceful fallback to import.raw() if URL import fails
• Better notifications showing success/failure status

Installation & Testing

• Setup: See plugin/README.md
• Testing: See plugin/TESTING.md
• Architecture: See docs/PLUGIN_ARCHITECTURE.md

🧪 Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type checking
npm run typecheck

# Linting
npm run lint
npm run lint:fix

# Formatting
npm run format
npm run format:check

# Build
npm run build

# Development mode (watch)
npm run dev

📝 Contributing

Contributions are welcome! Please see our Architecture Documentation for guidance on extending the project.

📄 License

MIT – use, fork, and adapt as needed.

🙏 Acknowledgments

Built with:

• Model Context Protocol SDK
• Zod for validation
• Vitest for testing