Skip to content
Back to search

Human-In-the-Loop-MCP-Server

A powerful 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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gongrzhe--human-in-the-loop-mcp-server/badge.svg)](/listings/gongrzhe--human-in-the-loop-mcp-server)

HTML

<a href="/listings/gongrzhe--human-in-the-loop-mcp-server"><img src="/api/listings/gongrzhe--human-in-the-loop-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Quick Install with uvx (Recommended)

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

Manual Installation

1. **Install from PyPI**:

   pip install hitl-mcp-server

2. **Run the server**:

   hitl-mcp-server
   # or
   hitl_mcp_server

Development Installation

1. **Clone the repository**:

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

2. **Install in development mode**:

   pip install -e .

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 416 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Human-In-the-Loop MCP Server
  2. ![](https://badge.mcpx.dev?type=server 'MCP Server')
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![PyPI version](https://badge.fury.io/py/hitl-mcp-server.svg)](https://badge.fury.io/py/hitl-mcp-server)
  5. 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.
  6. ![demo](demo.gif)
  7. ## 🚀 Features
  8. ### 💬 Interactive Dialog Tools
  9. - **Text Input**: Get text, numbers, or other data from users with validation
  10. - **Multiple Choice**: Present options for single or multiple selections
  11. - **Multi-line Input**: Collect longer text content, code, or detailed descriptions
  12. - **Confirmation Dialogs**: Ask for yes/no decisions before proceeding with actions
  13. - **Information Messages**: Display notifications, status updates, and results
  14. - **Health Check**: Monitor server status and GUI availability
  15. ### 🎨 Modern Cross-Platform GUI
  16. - **Windows**: Modern Windows 11-style interface with beautiful styling, hover effects, and enhanced visual design
  17. - **macOS**: Native macOS experience with SF Pro Display fonts and proper window management
  18. - **Linux**: Ubuntu-compatible GUI with modern styling and system fonts
  19. ### ⚡ Advanced Features
  20. - **Non-blocking Operation**: All dialogs run in separate threads to prevent blocking
  21. - **Timeout Protection**: Configurable 5-minute timeouts prevent hanging operations
  22. - **Platform Detection**: Automatic optimization for each operating system
  23. - **Modern UI Design**: Beautiful interface with smooth animations and hover effects
  24. - **Error Handling**: Comprehensive error reporting and graceful recovery
  25. - **Keyboard Navigation**: Full keyboard shortcuts support (Enter/Escape)
  26. ## 📦 Installation & Setup
  27. ### Quick Install with uvx (Recommended)
  28. The easiest way to use this MCP server is with `uvx`:
  29. ```bash
  30. # Install and run directly
  31. uvx hitl-mcp-server
  32. # Or use the underscore version
  33. uvx hitl_mcp_server
  34. ```
  35. ### Manual Installation
  36. 1. **Install from PyPI**:
  37. ```bash
  38. pip install hitl-mcp-server
  39. ```
  40. 2. **Run the server**:
  41. ```bash
  42. hitl-mcp-server
  43. # or
  44. hitl_mcp_server
  45. ```
  46. ### Development Installation
  47. 1. **Clone the repository**:
  48. ```bash
  49. git clone https://github.com/GongRzhe/Human-In-the-Loop-MCP-Server.git
  50. cd Human-In-the-Loop-MCP-Server
  51. ```
  52. 2. **Install in development mode**:
  53. ```bash
  54. pip install -e .
  55. ```
  56. ## 🔧 Claude Desktop Configuration
  57. To use this server with Claude Desktop, add the following configuration to your `claude_desktop_config.json`:
  58. ### Using uvx (Recommended)
  59. ```json
  60. {
  61. "mcpServers": {
  62. "human-in-the-loop": {
  63. "command": "uvx",
  64. "args": ["hitl-mcp-server"]
  65. }
  66. }
  67. }
  68. ```
  69. ### Using pip installation
  70. ```json
  71. {
  72. "mcpServers": {
  73. "human-in-the-loop": {
  74. "command": "hitl-mcp-server",
  75. "args": []
  76. }
  77. }
  78. }
  79. ```
  80. ### Configuration File Locations
  81. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  82. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  83. - **Linux**: `~/.config/Claude/claude_desktop_config.json`
  84. ### Important Note for macOS Users
  85. **Note:** You may need to allow Python to control your computer in **System Preferences > Security & Privacy > Accessibility** for the GUI dialogs to work properly.
  86. After updating the configuration, restart Claude Desktop for the changes to take effect.
  87. ## 🛠️ Available Tools
  88. ### 1. `get_user_input`
  89. Get single-line text, numbers, or other data from users.
  90. **Parameters:**
  91. - `title` (str): Dialog window title
  92. - `prompt` (str): Question/prompt text
  93. - `default_value` (str): Pre-filled value (optional)
  94. - `input_type` (str): "text", "integer", or "float" (default: "text")
  95. **Example Usage:**
  96. ```python
  97. result = await get_user_input(
  98. title="Project Setup",
  99. prompt="Enter your project name:",
  100. default_value="my-project",
  101. input_type="text"
  102. )
  103. ```
  104. ### 2. `get_user_choice`
  105. Present multiple options for user selection.
  106. **Parameters:**
  107. - `title` (str): Dialog window title
  108. - `prompt` (str): Question/prompt text
  109. - `choices` (List[str]): Available options
  110. - `allow_multiple` (bool): Allow multiple selections (default: false)
  111. **Example Usage:**
  112. ```python
  113. result = await get_user_choice(
  114. title="Framework Selection",
  115. prompt="Choose your preferred framework:",
  116. choices=["React", "Vue", "Angular", "Svelte"],
  117. allow_multiple=False
  118. )
  119. ```
  120. ### 3. `get_multiline_input`
  121. Collect longer text content, code, or detailed descriptions.
  122. **Parameters:**
  123. - `title` (str): Dialog window title
  124. - `prompt` (str): Question/prompt text
  125. - `default_value` (str): Pre-filled text (optional)
  126. **Example Usage:**
  127. ```python
  128. result = await get_multiline_input(
  129. title="Code Review",
  130. prompt="Please provide your detailed feedback:",
  131. default_value=""
  132. )
  133. ```
  134. ### 4. `show_confirmation_dialog`
  135. Ask for yes/no confirmation before proceeding.
  136. **Parameters:**
  137. - `title` (str): Dialog window title
  138. - `message` (str): Confirmation message
  139. **Example Usage:**
  140. ```python
  141. result = await show_confirmation_dialog(
  142. title="Delete Confirmation",
  143. message="Are you sure you want to delete these 5 files? This action cannot be undone."
  144. )
  145. ```
  146. ### 5. `show_info_message`
  147. Display information, notifications, or status updates.
  148. **Parameters:**
  149. - `title` (str): Dialog window title
  150. - `message` (str): Information message
  151. **Example Usage:**
  152. ```python
  153. result = await show_info_message(
  154. title="Process Complete",
  155. message="Successfully processed 1,247 records in 2.3 seconds!"
  156. )
  157. ```
  158. ### 6. `health_check`
  159. Check server status and GUI availability.
  160. **Example Usage:**
  161. ```python
  162. status = await health_check()
  163. # Returns detailed platform and functionality information
  164. ```
  165. ## 📋 Response Format
  166. All tools return structured JSON responses:
  167. ```json
  168. {
  169. "success": true,
  170. "user_input": "User's response text",
  171. "cancelled": false,
  172. "platform": "windows",
  173. "input_type": "text"
  174. }
  175. ```
  176. **Common Response Fields:**
  177. - `success` (bool): Whether the operation completed successfully
  178. - `cancelled` (bool): Whether the user cancelled the dialog
  179. - `platform` (str): Operating system platform
  180. - `error` (str): Error message if operation failed
  181. **Tool-Specific Fields:**
  182. - **get_user_input**: `user_input`, `input_type`
  183. - **get_user_choice**: `selected_choice`, `selected_choices`, `allow_multiple`
  184. - **get_multiline_input**: `user_input`, `character_count`, `line_count`
  185. - **show_confirmation_dialog**: `confirmed`, `response`
  186. - **show_info_message**: `acknowledged`
  187. ## 🧠 Best Practices for AI Integration
  188. ### When to Use Human-in-the-Loop Tools
  189. 1. **Ambiguous Requirements** - When user instructions are unclear
  190. 2. **Decision Points** - When you need user preference between valid alternatives
  191. 3. **Creative Input** - For subjective choices like design or content style
  192. 4. **Sensitive Operations** - Before executing potentially destructive actions
  193. 5. **Missing Information** - When you need specific details not provided
  194. 6. **Quality Feedback** - To get user validation on intermediate results
  195. ### Example Integration Patterns
  196. #### File Operations
  197. ```python
  198. # Get target directory
  199. location = await get_user_input(
  200. title="Backup Location",
  201. prompt="Enter backup directory path:",
  202. default_value="~/backups"
  203. )
  204. # Choose backup type
  205. backup_type = await get_user_choice(
  206. title="Backup Options",
  207. prompt="Select backup type:",
  208. choices=["Full Backup", "Incremental", "Differential"]
  209. )
  210. # Confirm before proceeding
  211. confirmed = await show_confirmation_dialog(
  212. title="Confirm Backup",
  213. message=f"Create {backup_type['selected_choice']} backup to {location['user_input']}?"
  214. )
  215. if confirmed['confirmed']:
  216. # Perform backup
  217. await show_info_message("Success", "Backup completed successfully!")
  218. ```
  219. #### Content Creation
  220. ```python
  221. # Get content requirements
  222. requirements = await get_multiline_input(
  223. title="Content Requirements",
  224. prompt="Describe your content requirements in detail:"
  225. )
  226. # Choose tone and style
  227. tone = await get_user_choice(
  228. title="Content Style",
  229. prompt="Select desired tone:",
  230. choices=["Professional", "Casual", "Friendly", "Technical"]
  231. )
  232. # Generate and show results
  233. # ... content generation logic ...
  234. await show_info_message("Content Ready", "Your content has been generated successfully!")
  235. ```
  236. ## 🔍 Troubleshooting
  237. ### Common Issues
  238. **GUI Not Appearing**
  239. - Verify you're running in a desktop environment (not headless server)
  240. - Check if tkinter is installed: `python -c "import tkinter"`
  241. - Run health check: `health_check()` tool to diagnose issues
  242. **Permission Errors (macOS)**
  243. - Grant accessibility permissions in System Preferences > Security & Privacy > Accessibility
  244. - Allow Python to control your computer
  245. - Restart terminal after granting permissions
  246. **Import Errors**
  247. - Ensure package is installed: `pip install hitl-mcp-server`
  248. - Check Python version compatibility (>=3.8 required)
  249. - Verify virtual environment activation if using one
  250. **Claude Desktop Integration Issues**
  251. - Check configuration file syntax and location
  252. - Restart Claude Desktop after configuration changes
  253. - Verify uvx is installed: `pip install uvx`
  254. - Test server manually: `uvx hitl-mcp-server`
  255. **Dialog Timeout**
  256. - Default timeout is 5 minutes (300 seconds)
  257. - Dialogs will return with cancelled=true if user doesn't respond
  258. - Ensure user is present when dialogs are triggered
  259. ### Debug Mode
  260. Enable detailed logging by running the server with environment variable:
  261. ```bash
  262. HITL_DEBUG=1 uvx hitl-mcp-server
  263. ```
  264. ## 🏗️ Development
  265. ### Project Structure
  266. ```
  267. Human-In-the-Loop-MCP-Server/
  268. ├── human_loop_server.py # Main server implementation
  269. ├── pyproject.toml # Package configuration
  270. ├── README.md # Documentation
  271. ├── LICENSE # MIT License
  272. ├── .gitignore # Git ignore rules
  273. └── demo.gif # Demo animation
  274. ```
  275. ### Contributing
  276. 1. Fork the repository
  277. 2. Create a feature branch: `git checkout -b feature-name`
  278. 3. Make your changes with proper testing
  279. 4. Follow code style guidelines (Black, Ruff)
  280. 5. Add type hints and docstrings
  281. 6. Submit a pull request with detailed description
  282. ### Code Quality
  283. - **Formatting**: Black (line length: 88)
  284. - **Linting**: Ruff with comprehensive rule set
  285. - **Type Checking**: MyPy with strict configuration
  286. - **Testing**: Pytest for unit and integration tests
  287. ## 🌍 Platform Support
  288. ### Windows
  289. - Windows 10/11 with modern UI styling
  290. - Enhanced visual design with hover effects
  291. - Segoe UI and Consolas font integration
  292. - Full keyboard navigation support
  293. ### macOS
  294. - Native macOS experience
  295. - SF Pro Display system fonts
  296. - Proper window management and focus
  297. - Accessibility permission handling
  298. ### Linux
  299. - Ubuntu/Debian compatible
  300. - Modern styling with system fonts
  301. - Cross-distribution GUI support
  302. - Minimal dependency requirements
  303. ## 📄 License
  304. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  305. ## 🤝 Acknowledgments
  306. - Built with [FastMCP](https://github.com/jlowin/fastmcp) framework
  307. - Uses [Pydantic](https://pydantic-docs.helpmanual.io/) for data validation
  308. - Cross-platform GUI powered by tkinter
  309. - Inspired by the need for human-AI collaboration
  310. ## 🔗 Links
  311. - **PyPI Package**: [https://pypi.org/project/hitl-mcp-server/](https://pypi.org/project/hitl-mcp-server/)
  312. - **Repository**: [https://github.com/GongRzhe/Human-In-the-Loop-MCP-Server](https://github.com/GongRzhe/Human-In-the-Loop-MCP-Server)
  313. - **Issues**: [Report bugs or request features](https://github.com/GongRzhe/Human-In-the-Loop-MCP-Server/issues)
  314. - **MCP Protocol**: [Learn about Model Context Protocol](https://modelcontextprotocol.io/)
  315. ## 📊 Usage Statistics
  316. - **Cross-Platform**: Windows, macOS, Linux
  317. - **Python Support**: 3.8, 3.9, 3.10, 3.11, 3.12+
  318. - **GUI Framework**: tkinter (built-in with Python)
  319. - **Thread Safety**: Full concurrent operation support
  320. - **Response Time**: < 100ms dialog initialization
  321. - **Memory Usage**: < 50MB typical operation
  322. ---
  323. **Made with ❤️ for the AI community - Bridging humans and AI through intuitive interaction**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.