Human In The Loop
STDIOMCP server providing interactive GUI dialogs for human-AI collaboration
MCP server providing interactive GUI dialogs for human-AI collaboration
A powerful Model Context Protocol (MCP) Server that enables AI assistants like Claude to interact with humans through intuitive GUI dialogs. This server bridges the gap between automated AI processes and human decision-making by providing real-time user input tools, choices, confirmations, and feedback mechanisms.
The easiest way to use this MCP server is with uvx:
# Install and run directly uvx hitl-mcp-server # Or use the underscore version uvx hitl_mcp_server
Install from PyPI:
pip install hitl-mcp-server
Run the server:
hitl-mcp-server # or hitl_mcp_server
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 .
To use this server with Claude Desktop, add the following configuration to your claude_desktop_config.json:
{ "mcpServers": { "human-in-the-loop": { "command": "uvx", "args": ["hitl-mcp-server"] } } }
{ "mcpServers": { "human-in-the-loop": { "command": "hitl-mcp-server", "args": [] } } }
%APPDATA%\Claude\claude_desktop_config.json~/Library/Application Support/Claude/claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonNote: You may need to allow Python to control your computer in System Preferences > Security & Privacy > Accessibility for the GUI dialogs to work properly.
After updating the configuration, restart Claude Desktop for the changes to take effect.
get_user_inputGet single-line text, numbers, or other data from users.
Parameters:
title (str): Dialog window titleprompt (str): Question/prompt textdefault_value (str): Pre-filled value (optional)input_type (str): "text", "integer", or "float" (default: "text")Example Usage:
result = await get_user_input( title="Project Setup", prompt="Enter your project name:", default_value="my-project", input_type="text" )
get_user_choicePresent multiple options for user selection.
Parameters:
title (str): Dialog window titleprompt (str): Question/prompt textchoices (List[str]): Available optionsallow_multiple (bool): Allow multiple selections (default: false)Example Usage:
result = await get_user_choice( title="Framework Selection", prompt="Choose your preferred framework:", choices=["React", "Vue", "Angular", "Svelte"], allow_multiple=False )
get_multiline_inputCollect longer text content, code, or detailed descriptions.
Parameters:
title (str): Dialog window titleprompt (str): Question/prompt textdefault_value (str): Pre-filled text (optional)Example Usage:
result = await get_multiline_input( title="Code Review", prompt="Please provide your detailed feedback:", default_value="" )
show_confirmation_dialogAsk for yes/no confirmation before proceeding.
Parameters:
title (str): Dialog window titlemessage (str): Confirmation messageExample Usage:
result = await show_confirmation_dialog( title="Delete Confirmation", message="Are you sure you want to delete these 5 files? This action cannot be undone." )
show_info_messageDisplay information, notifications, or status updates.
Parameters:
title (str): Dialog window titlemessage (str): Information messageExample Usage:
result = await show_info_message( title="Process Complete", message="Successfully processed 1,247 records in 2.3 seconds!" )
health_checkCheck server status and GUI availability.
Example Usage:
status = await health_check() # Returns detailed platform and functionality information
All tools return structured JSON responses:
{ "success": true, "user_input": "User's response text", "cancelled": false, "platform": "windows", "input_type": "text" }
Common Response Fields:
success (bool): Whether the operation completed successfullycancelled (bool): Whether the user cancelled the dialogplatform (str): Operating system platformerror (str): Error message if operation failedTool-Specific Fields:
user_input, input_typeselected_choice, selected_choices, allow_multipleuser_input, character_count, line_countconfirmed, responseacknowledged# Get target directory location = await get_user_input( title="Backup Location", prompt="Enter backup directory path:", default_value="~/backups" ) # Choose backup type backup_type = await get_user_choice( title="Backup Options", prompt="Select backup type:", choices=["Full Backup", "Incremental", "Differential"] ) # Confirm before proceeding confirmed = await show_confirmation_dialog( title="Confirm Backup", message=f"Create {backup_type['selected_choice']} backup to {location['user_input']}?" ) if confirmed['confirmed']: # Perform backup await show_info_message("Success", "Backup completed successfully!")
# Get content requirements requirements = await get_multiline_input( title="Content Requirements", prompt="Describe your content requirements in detail:" ) # Choose tone and style tone = await get_user_choice( title="Content Style", prompt="Select desired tone:", choices=["Professional", "Casual", "Friendly", "Technical"] ) # Generate and show results # ... content generation logic ... await show_info_message("Content Ready", "Your content has been generated successfully!")
GUI Not Appearing
python -c "import tkinter"health_check() tool to diagnose issuesPermission Errors (macOS)
Import Errors
pip install hitl-mcp-serverClaude Desktop Integration Issues
pip install uvxuvx hitl-mcp-serverDialog Timeout
Enable detailed logging by running the server with environment variable:
HITL_DEBUG=1 uvx hitl-mcp-server
Human-In-the-Loop-MCP-Server/
├── human_loop_server.py # Main server implementation
├── pyproject.toml # Package configuration
├── README.md # Documentation
├── LICENSE # MIT License
├── .gitignore # Git ignore rules
└── demo.gif # Demo animation
git checkout -b feature-nameThis project is licensed under the MIT License - see the LICENSE file for details.
Made with ❤️ for the AI community - Bridging humans and AI through intuitive interaction