Skip to main content
Glama
mcp-popup-ui

mcp-popup-ui

by jens-duttke

mcp-popup-ui

An MCP (Model Context Protocol) server that lets AI assistants ask you questions through a visual popup in your browser - instead of just printing text options.

MCP Popup UI in action with LM Studio

šŸ“¢ A Note on the Future

This project started as an experimental solution to a gap in the MCP ecosystem: letting AI assistants collect user input through a visual interface rather than plain text. It works today with any MCP-compatible client.

The MCP specification now includes MCP Apps - an official extension that embeds interactive UIs directly in the chat conversation. This provides a better user experience (no browser popup, no context switching) and will eventually be the recommended approach.

For now, mcp-popup-ui remains useful because MCP Apps support is still limited to a few clients (Claude, VS Code Insiders, Goose, Postman, MCPJam). Once MCP Apps becomes widely available, consider migrating to an MCP Apps-based solution for the best experience.

What This Does

When you chat with an AI assistant (like GitHub Copilot, Claude, or a local LLM), the AI sometimes needs your input - for example, "Which framework do you want?" or "Select the features to include."

Without this tool, the AI would print a numbered list and ask you to type your choice. With mcp-popup-ui, a clean popup opens in your browser where you can click your selection directly.

Two tools are provided:

Tool

Purpose

UI Element

ask_user

Pick exactly one option

Radio buttons

ask_user_multiple

Pick one or more options

Checkboxes

Related MCP server: Cloudflare Playwright MCP

Installation

Install globally via npm:

npm install -g mcp-popup-ui

Or run directly without installing:

npx y- mcp-popup-ui

Requirements: Node.js 18 or higher.

Setup

Choose the setup guide for your AI application:

VS Code (GitHub Copilot)

  1. Open your project folder in VS Code

  2. Create or edit the file .vscode/mcp.json:

    {
      "servers": {
        "popup-ui": {
          "command": "npx",
          "args": ["mcp-popup-ui"]
        }
      }
    }
  3. Restart VS Code or reload the window

LM Studio

  1. Open LM Studio settings

  2. Navigate to the MCP Servers section

  3. Add a new server with these settings:

    {
      "mcp-popup-ui": {
        "command": "npx",
        "args": ["mcp-popup-ui"]
      }
    }
  4. Enable the server and start a new chat

Ollama (via Open WebUI or similar)

Ollama itself does not natively support MCP. However, you can use it with frontends that support MCP, such as Open WebUI with MCP plugins. The configuration depends on your specific frontend - consult its documentation for adding MCP servers.

Claude Desktop

Add to your Claude Desktop configuration file:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "popup-ui": {
      "command": "npx",
      "args": ["mcp-popup-ui"]
    }
  }
}

Restart Claude Desktop after saving.

Copilot Instructions (Optional)

To ensure the AI uses the popup tools automatically instead of listing options in text, add this to your project's .github/copilot-instructions.md:

## User Input Collection

Use MCP tools for user choices:

- `ask_user` - single selection (radio buttons)
- `ask_user_multiple` - multiple selection (checkboxes)

Use these tools when presenting options like framework choices, implementation approaches, or any list of alternatives.

Tool Reference

ask_user

Displays a popup with radio buttons. The user picks exactly one option.

Parameters:

Parameter

Required

Description

options

Yes

Array of options (minimum 2). Each option has a label (required), optional description, and optional recommended flag.

title

No

Heading displayed above the options

description

No

Additional text displayed below the title

allow_other

No

If true, adds a text field for custom input

other_label

No

Label for the custom input option (default: "Other")

Example call:

{
  "options": [
    { "label": "React", "description": "Component-based UI library" },
    { "label": "Vue", "description": "Progressive JavaScript framework" },
    { "label": "Svelte", "description": "Compile-time framework", "recommended": true }
  ],
  "title": "Choose a Frontend Framework",
  "description": "Select one framework for your project."
}

Response:

{
  "action": "submit",
  "selection": "Svelte"
}

If the user clicks Skip:

{
  "action": "skip"
}

ask_user_multiple

Displays a popup with checkboxes. The user picks one or more options.

Parameters:

Parameter

Required

Description

options

Yes

Array of options (minimum 2). Each option has a label (required), optional description, and optional recommended flag.

title

No

Heading displayed above the options

description

No

Additional text displayed below the title

allow_other

No

If true, adds a text field for custom input

other_label

No

Label for the custom input option (default: "Other")

Example call:

{
  "options": [
    { "label": "TypeScript", "recommended": true },
    { "label": "ESLint" },
    { "label": "Prettier" },
    { "label": "Jest" }
  ],
  "title": "Select Project Features",
  "description": "Choose all features to include."
}

Response:

{
  "action": "submit",
  "selections": ["TypeScript", "ESLint", "Prettier"]
}

Additional Features

  • Skip button: Users can skip any question without selecting an option

  • Comments field: Users can add additional notes with their selection

  • Explanation request: Users can ask for more details about an option before deciding

  • Markdown support: Option descriptions support Markdown formatting

Documentation

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

Available Tools

2 tools
ask_userA

Ask the user to choose exactly ONE option from a list. Use this tool instead of listing options in your text response whenever you need the user to make a decision.

WHEN TO USE THIS TOOL:

  • You are about to list numbered options and ask "which do you prefer?"

  • You need user confirmation on a specific choice before proceeding

  • The user must pick one mutually exclusive option (e.g., "Which approach should I implement?", "Which file should I modify?", "What framework do you want?")

EXAMPLES OF WHEN TO USE:

  • "Should I use Option A, B, or C?" → Use this tool

  • "Which implementation approach?" → Use this tool

  • "What programming language?" → Use this tool

  • "Pick a template to scaffold" → Use this tool

āš ļø CRITICAL: Each parameter MUST be passed SEPARATELY. Do NOT combine them!

āŒ WRONG (options contains title/description - WILL FAIL): options: [{"label": "A"}, {"label": "B"}], "title": "...", "description": "..."

āœ… CORRECT (each parameter separate): options: [{"label": "A"}, {"label": "B"}] title: "Pick one" description: "Choose your preference"

PARAMETERS:

  • options (REQUIRED): Array of objects, each with "label" (required) and optional "description", "recommended"

  • title (optional): String displayed above options

  • description (optional): String displayed below title

  • allow_other (optional): Boolean to allow custom input

The tool opens a popup in the user's browser and waits for their selection. If allow_other is true, users can enter custom text if predefined options don't fit. Returns the selected option as a string, or indicates if the user skipped.

Inputs: options (required), title, allow_other, description, +1 more. Returns: action, comments, selection, explainOption, +1 more

ask_user_multipleA

Ask the user to choose ONE OR MORE options from a list. Use this tool instead of listing options in your text response whenever the user can select multiple items.

WHEN TO USE THIS TOOL:

  • You are about to list items and ask "which ones do you want?" or "select all that apply"

  • The user can pick multiple non-exclusive options (e.g., "Which features to include?", "Which files to modify?", "What languages do you know?")

  • You need to gather multiple preferences at once

EXAMPLES OF WHEN TO USE:

  • "Which features do you want?" → Use this tool

  • "Select the files to include" → Use this tool

  • "What integrations should I add?" → Use this tool

  • "Pick all applicable tags" → Use this tool

āš ļø CRITICAL: Each parameter MUST be passed SEPARATELY. Do NOT combine them!

āŒ WRONG (options contains title/description - WILL FAIL): options: [{"label": "A"}, {"label": "B"}], "title": "...", "description": "..."

āœ… CORRECT (each parameter separate): options: [{"label": "A"}, {"label": "B"}] title: "Select features" description: "Choose all that apply"

PARAMETERS:

  • options (REQUIRED): Array of objects, each with "label" (required) and optional "description", "recommended"

  • title (optional): String displayed above options

  • description (optional): String displayed below title

  • min_selections (optional): Minimum selections required

  • max_selections (optional): Maximum selections allowed

  • allow_other (optional): Boolean to allow custom input

The tool opens a popup in the user's browser and waits for their selections. If allow_other is true, users can add custom text if predefined options don't fit. Returns an array of selected options, or indicates if the user skipped.

Inputs: options (required), title, allow_other, description, +1 more. Returns: action, comments, selections, explainOption, +1 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools are clearly differentiated by singular vs. plural selection. Ask_user restricts to exactly one option, while ask_user_multiple allows multiple selections, with descriptions emphasizing this distinction.

    Naming Consistency5/5

    Both tools follow a consistent snake_case verb_noun pattern: ask_user and ask_user_multiple. The naming clearly communicates the shared purpose and the single/multiple distinction.

    Tool Count3/5

    With only 2 tools, the server feels thin, especially given the broader 'popup-ui' name. The two selection modes cover a narrow niche, and while they are well-defined, the overall surface is minimal.

    Completeness3/5

    The tools handle single and multiple choice popups, but other common popup interactions such as free-form text input, simple confirmations, or informational dialogs are missing. Agents must rely on allow_other for custom input, which is not ideal, leaving notable gaps.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to automate web browsers through Playwright, providing capabilities for navigation, content extraction, form filling, screenshot capture, and JavaScript execution. Supports multiple browser engines with comprehensive error handling and security features.
      1
      -