The Human-In-the-Loop MCP Server provides a GUI-based layer that allows AI agents to request real-time human input through intuitive dialogs. Use cases include collecting single-line text, numbers, or longer content; offering multiple-choice selections (single or multiple); prompting for confirmations before sensitive actions; and displaying status updates or information messages. Core tools exposed by the server are get_user_input, get_user_choice, get_multiline_input, show_confirmation_dialog, show_info_message, and health_check, which enable AI workflows to pause for human decisions or feedback when needed. When integrated with MCP-enabled agents (for example, Claude or other compliant assistants), the server surfaces lightweight, thread-safe dialogs to keep the AI process responsive while humans provide input via a cross-platform GUI. To run it in your Claude Desktop workflow, configure the claude_desktop_config.json to point at the uvx wrapper as shown in the setup instructions.

Prerequisites:

• Python 3.8+ and pip are available on your system
• Internet access to install dependencies
• Optional: uvx (the preferred distribution method) for a quick start

Installation methods:

1. Quick start with uvx (recommended)

• Install and run directly: uvx hitl-mcp-server

• Or use the underscore version: uvx hitl_mcp_server

2. Install from PyPI (standalone Python package)

• Install: pip install hitl-mcp-server
• Run: hitl-mcp-server

  or

  hitl_mcp_server

3. Development installation

• Clone the repository: git clone https://github.com/GongRzhe/Human-In-the-Loop-MCP-Server.git cd Human-In-the-Loop-MCP-Server
• Install in development mode: pip install -e .
• Run the server: hitl-mcp-server

Notes:

• If you encounter permission or GUI-related issues on macOS, ensure Python has the required Accessibility permissions in System Preferences.

Tips and common issues:

• Environment variables: you generally don’t need to set them for basic operation, but you can configure GUI behavior or logging via your environment if the project exposes such options in your deployment. Refer to the project’s code/docs for any optional env vars.
• macOS users: you may need to allow Python to control your computer in System Preferences > Security & Privacy > Accessibility for the GUI dialogs to work properly.
• Timeouts: dialogs include configurable 5-minute timeouts to prevent hanging operations; adjust as needed in your deployment configuration if supported.
• Claude Desktop integration: when wiring with Claude Desktop, place the appropriate mcpServers configuration in claude_desktop_config.json as documented (uvx-based or direct execution) and restart Claude Desktop after changes.
• GUI performance: dialogs run in separate threads to avoid blocking the MCP workflow; ensure your host machine has sufficient CPU/RAM if presenting complex dialogs or long-running operations.