by GongRzhe
Enables AI assistants to collect real-time user input, choices, confirmations, and feedback through intuitive cross‑platform GUI dialogs.
Provides a Model Context Protocol server that lets AI models like Claude show interactive dialogs (text input, multiple choice, multiline input, confirmations, info messages) to end‑users on Windows, macOS, and Linux. The dialogs run in separate threads, include timeout protection, and return structured JSON responses.
uvx
:
uvx hitl-mcp-server
Or install from PyPI: pip install hitl-mcp-server
and run hitl-mcp-server
.claude_desktop_config.json
pointing to the command (uvx hitl-mcp-server
or the installed executable).get_user_input
, get_user_choice
, get_multiline_input
, show_confirmation_dialog
, show_info_message
, health_check
). Each returns a JSON payload indicating success, user response, platform, and possible errors.hitl-mcp-server
) before the AI assistant starts sending MCP calls.Q: Do I need a graphical environment? A: Yes, the dialogs require a desktop environment; they will not work on headless servers.
Q: Which Python versions are supported? A: Python 3.8 and newer (3.9‑3.12+).
Q: How do I handle macOS permission issues? A: Grant Python accessibility permissions via System Preferences → Security & Privacy → Accessibility.
Q: What happens if a user cancels a dialog?
A: The response JSON includes "cancelled": true
and success
will be false
.
Q: Can I change the default timeout?
A: Yes, adjust the timeout
parameter when invoking the tool (if exposed) or modify the server configuration source.
Q: How do I debug the server?
A: Set the environment variable HITL_DEBUG=1
before starting the server to enable detailed logging.
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.json
Note: 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_input
Get 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_choice
Present 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_input
Collect 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_dialog
Ask 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_message
Display 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_check
Check 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_type
selected_choice
, selected_choices
, allow_multiple
user_input
, character_count
, line_count
confirmed
, response
acknowledged
# 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-server
Claude Desktop Integration Issues
pip install uvx
uvx hitl-mcp-server
Dialog 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-name
This 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
Please log in to share your review and rating for this MCP.
{ "mcpServers": { "human-in-the-loop": { "command": "uvx", "args": [ "hitl-mcp-server" ], "env": {} } } }
Discover more MCP servers with similar functionality and use cases
by elie222
An AI‑powered email assistant that automates inbox management, enabling users to reach inbox zero fast by handling replies, labeling, archiving, unsubscribing, and providing analytics through a plain‑text prompt configuration.
by makenotion
Provides a remote Model Context Protocol server for the Notion API, enabling OAuth‑based installation and optimized toolsets for AI agents with minimal token usage.
by sooperset
MCP Atlassian is a Model Context Protocol (MCP) server that integrates AI assistants with Atlassian products like Confluence and Jira. It enables AI to automate tasks, search for information, and manage content within Atlassian ecosystems.
by ggozad
Interact with Ollama models through an intuitive terminal UI, supporting persistent chats, system prompts, model parameters, and MCP tools integration.
by nbonamy
A desktop AI assistant that bridges dozens of LLM, image, video, speech, and search providers, offering chat, generative media, RAG, shortcuts, and extensible plugins directly from the OS.
by GongRzhe
Provides tools for creating, editing, and enhancing PowerPoint presentations through a comprehensive set of MCP operations powered by python-pptx.
by GongRzhe
Creates, reads, and manipulates Microsoft Word documents through a standardized interface for AI assistants, enabling rich editing, formatting, and analysis capabilities.
by GongRzhe
Gmail-MCP-Server is a Model Context Protocol (MCP) server that integrates Gmail functionalities into AI assistants like Claude Desktop. It enables natural language interaction for email management, supporting features like sending, reading, and organizing emails.
by nspady
google-calendar-mcp is a Model Context Protocol (MCP) server that integrates Google Calendar with AI assistants. It enables AI assistants to manage Google Calendar events, including creating, updating, deleting, and searching for events.