mcp-pop-up

An MCP server that lets a local LLM ask you for guidance through a native desktop pop-up — just like the question prompts Claude shows in the app.

The model calls a single tool, ask_user, with a question and up to 6 suggested answers. An "Other" free-text choice is always added automatically, and the model decides whether you may pick one answer (radio buttons) or several (checkboxes). Your choice is returned to the model so it knows how to proceed.

Built for LM Studio, but it works with any MCP client that speaks stdio.

---

How it works

LM Studio ─stdio─► mcp_pop_up.server ─subprocess─► mcp_pop_up.dialog (tkinter)
   ▲                                                          │
   └──────────────  "The user selected: …"  ◄─────────────────┘

The server exposes the ask_user tool. When called, it launches the dialog in a short-lived subprocess to render the Tk window. Running the GUI in its own process keeps the blocking Tk event loop from colliding with the server's async loop, and works reliably across Windows, macOS, and Linux.

The code is split so each module has one job:

Module	Responsibility
mcp_pop_up/protocol.py	Request/result data model — validation, JSON (de)serialization, and result formatting. The single source of truth for the contract; depends on neither mcp nor tkinter.
mcp_pop_up/server.py	The FastMCP server and the ask_user tool.
mcp_pop_up/runner.py	Launches the dialog subprocess and parses its result.
mcp_pop_up/dialog/view.py	The PopupDialog tkinter window.
mcp_pop_up/dialog/__main__.py	Subprocess entry point: stdin → dialog → stdout.
server.py (root)	Thin launcher so clients can point at a file path without installing.

---

The ask_user tool

Argument	Type	Default	Description
question	string	—	The question shown to the user (required).
options	string[]	[]	Up to 6 suggested answers. May be empty for an open-ended question.
allow_multiple	boolean	false	true → checkboxes (pick several). false → radio buttons (pick one).

An "Other (type your own answer)" choice with a text box is always appended, so the user is never limited to the options you provide.

Returns a short human-readable summary, e.g.:

• The user selected: Wait for review
• The user selected 2 options:\n- Lint\n- Build
• The user selected: Refactor the parser first (typed into "Other")
• The user cancelled the pop-up without choosing an answer.

---

Requirements

• Python 3.10+
• tkinter — bundled with the standard Python installers on Windows and macOS. On Linux install it separately:

  sudo apt install python3-tk      # Debian/Ubuntu
  sudo dnf install python3-tkinter # Fedora
  

• The mcp Python SDK (installed below).

Install

git clone https://github.com/GiantBeaver9/mcp-pop-up.git
cd mcp-pop-up
pip install -r requirements.txt        # just the runtime dep, or:
pip install -e .                        # installs the `mcp-pop-up` command too

Verify it starts (Ctrl-C to stop — it waits silently for a client on stdio):

python server.py          # via the file-path launcher, or:
python -m mcp_pop_up       # via the package, or:
mcp-pop-up                 # via the console script (after `pip install -e .`)

---

Configure LM Studio

LM Studio manages MCP servers through its mcp.json file (Program → Edit mcp.json, or the "Integrations" / MCP settings panel). Add this entry, using an absolute path to the launcher:

{
  "mcpServers": {
    "pop-up": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-pop-up/server.py"]
    }
  }
}

On Windows, use python (or the full path to python.exe) and a full path such as C:\\Users\\you\\mcp-pop-up\\server.py.

The root server.py launcher works without installing the package. If you ran pip install -e ., you can instead use "command": "mcp-pop-up", "args": [], or "args": ["-m", "mcp_pop_up"].

Reload the MCP servers in LM Studio. The ask_user tool should now appear and be available to the model. Ask your model something like "Ask me whether to deploy now or wait, then act on my answer" to see the pop-up.

Tip: Make sure LM Studio runs the same Python interpreter that has both mcp and tkinter installed — the server launches the dialog with that same interpreter.

Use with other MCP clients

Any stdio MCP client works. Point it at python /absolute/path/to/server.py.

---

Project layout

mcp-pop-up/
├── server.py                 # thin launcher (point MCP clients here)
├── pyproject.toml            # packaging + `mcp-pop-up` console script
├── requirements.txt          # runtime dependency (mcp)
└── mcp_pop_up/
    ├── __main__.py           # `python -m mcp_pop_up` → server
    ├── protocol.py           # request/result model: validation + JSON + formatting
    ├── server.py             # FastMCP server + the `ask_user` tool
    ├── runner.py             # launches the dialog subprocess, parses its result
    └── dialog/
        ├── __main__.py       # subprocess entry: stdin → dialog → stdout
        └── view.py           # PopupDialog tkinter window

Troubleshooting

• GUI is unavailable: No module named 'tkinter' — install tkinter for the interpreter LM Studio uses (see Requirements).
• No window appears — the pop-up shows on the machine running the server. It needs a desktop session; it won't display over a headless SSH connection.
• Tool doesn't show up in LM Studio — double-check the absolute path in mcp.json and reload the MCP servers.