HumanBridge MCP Server

by Jatin Iyer

A Model Context Protocol (MCP) Server that enables AI assistants to interact with humans through polished, modern GUI dialogs. HumanBridge bridges the gap between automated AI processes and human decision-making — providing text input, multiple choice, confirmations, and info notifications, all in dynamically-sized, scrollable windows that never overflow your screen.

---

Features

• Text Input — get text, numbers, or other data with validation
• Multiple Choice — single or multi-select option lists
• Multi-line Input — collect code, descriptions, or long-form content
• Confirmation Dialogs — yes/no decisions before proceeding
• Information Messages — display notifications and status updates
• Health Check — monitor server and GUI availability
• Dynamic sizing — windows grow to fit content, cap at 80% screen height, then scroll
• Scrollable content — title/prompt area scrolls automatically when text is long
• Cross-platform — Windows 11-style, macOS native, Linux compatible

---

Installation

Quick Install with uvx (Recommended)

uvx humanbridge-mcp

pip

pip install humanbridge-mcp
humanbridge-mcp

---

Configuration

VS Code GitHub Copilot

Add to your VS Code settings.json or .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "humanbridge": {
        "command": "uvx",
        "args": ["humanbridge-mcp"]
      }
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "humanbridge": {
      "command": "uvx",
      "args": ["humanbridge-mcp"]
    }
  }
}

Restart after updating the config.

---

Available Tools

get_user_input

Single-line text, integer, or float input.

Parameter	Type	Description
title	str	Dialog window title
prompt	str	Question shown to user
default_value	str	Pre-filled value (optional)
input_type	str	"text", "integer", or "float"

get_user_choice

Pick one or many options from a list.

Parameter	Type	Description
title	str	Dialog window title
prompt	str	Question shown to user
choices	list[str]	Options to present
allow_multiple	bool	Allow multi-select (default: false)

get_multiline_input

Large text area for code, descriptions, or long content.

Parameter	Type	Description
title	str	Dialog window title
prompt	str	Question shown to user
default_value	str	Pre-filled text (optional)

show_confirmation_dialog

Yes/No decision dialog.

Parameter	Type	Description
title	str	Dialog window title
message	str	Confirmation message

show_info_message

Informational notification — user clicks OK to dismiss.

Parameter	Type	Description
title	str	Dialog window title
message	str	Information message

health_check

Returns server status, platform details, and GUI availability.

---

Response Format

All tools return structured JSON:

{
  "success": true,
  "user_input": "User's response",
  "cancelled": false,
  "platform": "windows"
}

Common fields: success, cancelled, platform, error
Tool-specific: user_input, input_type, selected_choice, selected_choices, confirmed, response, acknowledged, character_count, line_count

---

Dialog Behaviour

• Short content: window sizes exactly to content — compact and clean
• Long content: window grows up to 80% of screen height, then the title/prompt area becomes scrollable (mousewheel supported)
• Input widgets (entry field, text area, choice list) are always fully visible — they never scroll away
• All dialogs are resizable by the user

---

Troubleshooting

Dialogs not appearing

• Verify you're in a desktop environment (not headless)
• Check tkinter: python -c "import tkinter"
• Run health_check tool to diagnose

macOS permission error

• Grant Accessibility permissions: System Preferences → Security & Privacy → Accessibility

Dialog timeout

• Default timeout is 5 minutes. Dialogs return cancelled: true after timeout.

---

Platform Support

Platform	Status	Notes
Windows 10/11	✅ Full	Modern Windows 11-style UI, Segoe UI font
macOS	✅ Full	SF Pro Display font, Accessibility permission needed
Linux	✅ Full	Ubuntu/Debian compatible, system fonts

---

License

MIT License — see LICENSE

---

HumanBridge MCP Server by Jatin Iyer