Human-In-the-Loop MCP Server

Enables AI assistants to interact with humans through GUI dialogs for input, choices, and confirmations.

A powerfulModel Context Protocol (MCP) Serverthat 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.

- Text Input: Get text, numbers, or other data from users with validation
- Multiple Choice: Present options for single or multiple selections
- Multi-line Input: Collect longer text content, code, or detailed descriptions
- Confirmation Dialogs: Ask for yes/no decisions before proceeding with actions
- Information Messages: Display notifications, status updates, and results
- Health Check: Monitor server status and GUI availability

- Windows: Modern Windows 11-style interface with beautiful styling, hover effects, and enhanced visual design
- macOS: Native macOS experience with SF Pro Display fonts and proper window management
- Linux: Ubuntu-compatible GUI with modern styling and system fonts

- Non-blocking Operation: All dialogs run in separate threads to prevent blocking
- Timeout Protection: Configurable 5-minute timeouts prevent hanging operations
- Platform Detection: Automatic optimization for each operating system
- Modern UI Design: Beautiful interface with smooth animations and hover effects
- Error Handling: Comprehensive error reporting and graceful recovery
- Keyboard Navigation: Full keyboard shortcuts support (Enter/Escape)

The easiest way to use this MCP server is withuvx:

# Install and run directly uvx hitl-mcp-server # Or use the underscore version uvx hitl_mcp_server

git clone https://github.com/GongRzhe/Human-In-the-Loop-MCP-Server.git cd Human-In-the-Loop-MCP-Server

To use this server with Claude Desktop, add the following configuration to yourclaude_desktop_config.json:

{ "mcpServers": { "human-in-the-loop": { "command": "uvx", "args": ["hitl-mcp-server"] } } }

{ "mcpServers": { "human-in-the-loop": { "command": "hitl-mcp-server", "args": [] } } }

- Windows:%APPDATA%\Claude\claude_desktop_config.json
- macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Linux:~/.config/Claude/claude_desktop_config.json

Note:You may need to allow Python to control your computer inSystem Preferences > Security & Privacy > Accessibilityfor the GUI dialogs to work properly.

After updating the configuration, restart Claude Desktop for the changes to take effect.

Get single-line text, numbers, or other data from users.

- title(str): Dialog window title
- prompt(str): Question/prompt text
- default_value(str): Pre-filled value (optional)
- input_type(str): "text", "integer", or "float" (default: "text")

result = await get_user_input( title="Project Setup", prompt="Enter your project name:", default_value="my-project", input_type="text" )

Present multiple options for user selection.

- title(str): Dialog window title
- prompt(str): Question/prompt text
- choices(List[str]): Available options
- allow_multiple(bool): Allow multiple selections (default: false)

result = await get_user_choice( title="Framework Selection", prompt="Choose your preferred framework:", choices=["React", "Vue", "Angular", "Svelte"], allow_multiple=False )

Collect longer text content, code, or detailed descriptions.

- title(str): Dialog window title
- prompt(str): Question/prompt text
- default_value(str): Pre-filled text (optional)

result = await get_multiline_input( title="Code Review", prompt="Please provide your detailed feedback:", default_value="" )

Ask for yes/no confirmation before proceeding.

- title(str): Dialog window title
- message(str): Confirmation message

result = await show_confirmation_dialog( title="Delete Confirmation", message="Are you sure you want to delete these 5 files? This action cannot be undone." )

Display information, notifications, or status updates.

- title(str): Dialog window title
- message(str): Information message

result = await show_info_message( title="Process Complete", message="Successfully processed 1,247 records in 2.3 seconds!" )

Check server status and GUI availability.

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" }

- success(bool): Whether the operation completed successfully
- cancelled(bool): Whether the user cancelled the dialog
- platform(str): Operating system platform
- error(str): Error message if operation failed

- get_user_input:user_input,input_type
- get_user_choice:selected_choice,selected_choices,allow_multiple
- get_multiline_input:user_input,character_count,line_count
- show_confirmation_dialog:confirmed,response
- show_info_message:acknowledged
- Ambiguous Requirements- When user instructions are unclear
- Decision Points- When you need user preference between valid alternatives
- Creative Input- For subjective choices like design or content style
- Sensitive Operations- Before executing potentially destructive actions
- Missing Information- When you need specific details not provided
- Quality Feedback- To get user validation on intermediate results

# 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!")

- Verify you're running in a desktop environment (not headless server)
- Check if tkinter is installed:python -c "import tkinter"
- Run health check:health_check()tool to diagnose issues

- Grant accessibility permissions in System Preferences > Security & Privacy > Accessibility
- Allow Python to control your computer
- Restart terminal after granting permissions

- Ensure package is installed:pip install hitl-mcp-server
- Check Python version compatibility (>=3.8 required)
- Verify virtual environment activation if using one

- Check configuration file syntax and location
- Restart Claude Desktop after configuration changes
- Verify uvx is installed:pip install uvx
- Test server manually:uvx hitl-mcp-server

- Default timeout is 5 minutes (300 seconds)
- Dialogs will return with cancelled=true if user doesn't respond
- Ensure user is present when dialogs are triggered

Enable detailed logging by running the server with environment variable:

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

- Fork the repository
- Create a feature branch:git checkout -b feature-name
- Make your changes with proper testing
- Follow code style guidelines (Black, Ruff)
- Add type hints and docstrings
- Submit a pull request with detailed description

- Formatting: Black (line length: 88)
- Linting: Ruff with comprehensive rule set
- Type Checking: MyPy with strict configuration
- Testing: Pytest for unit and integration tests

- Windows 10/11 with modern UI styling
- Enhanced visual design with hover effects
- Segoe UI and Consolas font integration
- Full keyboard navigation support

- Native macOS experience
- SF Pro Display system fonts
- Proper window management and focus
- Accessibility permission handling

- Ubuntu/Debian compatible
- Modern styling with system fonts
- Cross-distribution GUI support
- Minimal dependency requirements

This project is licensed under the MIT License - see theLICENSEfile for details.

- Built withFastMCPframework
- UsesPydanticfor data validation
- Cross-platform GUI powered by tkinter
- Inspired by the need for human-AI collaboration

- PyPI Package:https://pypi.org/project/hitl-mcp-server/
- Repository:https://github.com/GongRzhe/Human-In-the-Loop-MCP-Server
- Issues:Report bugs or request features
- MCP Protocol:Learn about Model Context Protocol

Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client, with persistent identity, real-time messaging with @mentions and threads, task handoffs, shared workspace context, semantic search, and replayable MCP App widgets.