mcp-gui

The MCP GUI Server provides a modern graphical interface for collecting user input and orchestrating interactive prompts within MCP-enabled clients. It exposes an interactive web UI that supports image uploads, persistent terminal-like command execution, and real-time feedback workflows. The server integrates with multiple LLM providers through an abstraction layer, enabling prompt engineering enhancements and multi-provider routing. After enabling the GUI tool in your MCP client (via the gui-input tool), you can launch prompts that request structured user input, media uploads, or terminal commands, all within a secure session that can auto-expire and clean up when complete.

Prerequisites:

• Node.js 18+ (recommended)
• pnpm 8+ (recommended) or npm/yarn as an alternative

Option A: Run with NPX (no install required)

• Ensure you have Node.js installed
• Run: npx mcp-gui-server

Option B: Install from source (development or customization)

• Clone the repository: git clone https://github.com/oqwn/mcp-gui-server.git
• Navigate to the project directory: cd mcp-gui-server
• Install dependencies (pnpm recommended): pnpm install
• Build the project: pnpm run build
• Start the server: pnpm start

Prerequisites for development:

• pnpm installed globally (npm install -g pnpm)
• Optional: Docker or other deployment options if you prefer containerization

Tips and common considerations:

• If you encounter port 3501 in use, the server will auto-find an available port (e.g., 3517). Check console logs for the selected port.
• Environment variables under OPENROUTER_ are used to configure the OpenRouter integration. Replace placeholders with your API key, base URL, and model as needed.
• The NPX approach is ideal for testing; for production or custom deployments, install from source and run pnpm start to serve in your environment.
• The GUI supports image uploads (JPG, PNG, GIF, WebP) up to 10MB per image, with base64 embedding in MCP responses for multimodal workflows.
• If you run into NPX issues, consider clearing the npm cache or installing the package globally, then invoking mcp-gui-server directly.
• The server includes built-in session management, persistent terminal sessions, and hot-reloading during development.