mcp-tui

README

MCP-TUI

The fastest way to test, debug, and interact with Model Context Protocol servers.

Stop struggling with curl commands, JSON formatting, and connection issues. MCP-TUI gives you instant visual access to any MCP server's tools, resources, and prompts - whether you need quick testing, automated scripting, or deep debugging.

🎯 Why Choose MCP-TUI?

For Developers:

• ⚡ Zero Setup Testing - Connect to any MCP server in one command, no configuration files needed
• 🔍 Visual Debugging - See exactly what your server exposes and how it responds in real-time
• 🤖 Automation Ready - Script complex workflows with full CLI automation support
• 🛡️ Production Confidence - Test error scenarios with included problematic servers before deployment

For Teams:

• 📋 Consistent Testing - Standardized interface for testing all MCP servers across your organization
• 🌍 Universal Compatibility - Works with any MCP server regardless of language or transport method
• 📊 Clear Reporting - Structured output perfect for CI/CD pipelines and documentation
• 🚀 Faster Development - Reduce debugging time from hours to minutes

✨ What You Get

Interactive Visual Interface

Problem Solved: No more writing curl commands or parsing JSON responses manually

• Browse all available tools, resources, and prompts in an intuitive interface
• Execute tools with guided form inputs and see results immediately
• Real-time progress tracking for long-running operations
• Built-in clipboard support for easy data transfer

Scriptable Automation

Problem Solved: Integrate MCP testing into CI/CD pipelines and automated workflows

• Full command-line interface for scripting and automation
• JSON output support for integration with other tools
• Batch operations and parallel execution capabilities
• Exit codes and error handling perfect for scripts

Transport Support

Problem Solved: Connect to MCP servers with reliable, standards-compliant transport

• ✅ STDIO transport for local processes and command execution
• ✅ SSE (Server-Sent Events) transport for web services and cloud deployments
• ✅ HTTP transport for standard web APIs and RESTful services
• ✅ Streamable HTTP transport for advanced MCP protocol compliance
• Built on official MCP Go SDK for maximum compatibility and protocol compliance

Robust Error Handling

Problem Solved: Understand exactly what's wrong when servers misbehave

• Structured error messages with actionable guidance
• Comprehensive debug logging for deep troubleshooting
• Test servers that simulate real-world failure scenarios
• Graceful degradation when servers become unresponsive

Enhanced Navigation & File Discovery

Problem Solved: Stop re-typing server configurations and struggle to find existing configs

• Tabbed interface with visual navigation between saved/discovered/manual modes
• Smart file discovery automatically finds Claude Desktop, VS Code, and MCP configs
• Combined command input - type "brum --mcp" in one field, not separate command/args
• Arrow key navigation between tabs and intuitive UI flow
• Auto-connect to single server setups or configured default servers
• Compatible with Claude Desktop and VS Code MCP configurations
• Recent connections tracking with success status
• Environment variable substitution for secure credential management

🚀 Get Started in 30 Seconds

Installation

Option 1: Go (Recommended)

go install github.com/standardbeagle/mcp-tui@latest

Benefits: Always up-to-date, fastest installation, works offline

Option 2: npm

npm install -g @standardbeagle/mcp-tui
# or use directly: npx @standardbeagle/mcp-tui

Benefits: Familiar for Node.js developers, automatic updates

Option 3: Build from source

git clone https://github.com/standardbeagle/mcp-tui.git
cd mcp-tui
make install

Benefits: Latest features, customizable, contribute back

Instant Connection - Enhanced Experience

✨ New in v0.2.0: Revolutionary UI with saved connections, file discovery, tabbed navigation, and combined command input. Built on the official MCP Go SDK with comprehensive security validation.

🎯 Just Getting Started? Try This:

# Open the enhanced TUI with file discovery and saved connections
mcp-tui

# Quick connect to MCP server via STDIO (single command line)
mcp-tui "npx -y @modelcontextprotocol/server-everything stdio"

# Or connect via SSE (Server-Sent Events) for web servers
mcp-tui --url http://localhost:8000/sse

What's new: Visual tabs, file discovery finds existing configs, combined command input, arrow key navigation

💡 Smart Auto-Connect: If you have a saved configuration file with a single server or default server, MCP-TUI will auto-connect immediately:

# Create ~/.config/mcp-tui/connections.json or copy examples/single-server-config.json
mcp-tui  # Connects automatically!

🤖 Building Automation? Use CLI Mode:

# List all available tools via STDIO (combined command input) 
mcp-tui "npx -y @modelcontextprotocol/server-everything stdio" tool list

# Or via SSE
mcp-tui --url http://localhost:8000/sse tool list

# Execute a specific tool with parameters
mcp-tui --url http://localhost:8000/sse tool call echo message="Hello World"

# Get JSON output for your scripts
mcp-tui --json --url http://localhost:8000/sse tool list

Why this works: Combined command input, perfect for CI/CD, scripts, and automated testing workflows

🌐 Have a Web Service? Connect via HTTP:

# Visual interface for web-based MCP servers
mcp-tui --url http://localhost:8000/mcp

# Automated testing of web services
mcp-tui --url http://localhost:8000/mcp tool list

Why this works: No need to understand HTTP protocols, handles authentication automatically

🔧 Need Interactive Setup?

# Guided connection setup with helpful prompts
mcp-tui

Why this works: Perfect when you're exploring or don't know the exact server parameters

🎮 Real-World Usage Scenarios

Scenario 1: Testing Your New MCP Server

# Start your server development with confidence
mcp-tui "python my_awesome_server.py"

What happens: Instantly see all tools your server exposes, test each one interactively, catch errors before your users do.

Scenario 2: CI/CD Integration Testing

# Add to your GitHub Actions or CI pipeline
mcp-tui --json "docker run my-mcp-server" tool list | jq '.tools | length'

What happens: Automated verification that your server deployment is working correctly.

Scenario 3: Debugging Production Issues

# Quickly diagnose what's wrong with a misbehaving server
mcp-tui --debug --log-level debug "problematic-server-command"

What happens: Detailed logs show exactly where communication breaks down.

Scenario 4: API Documentation Generation

# Generate documentation from your server's actual capabilities
mcp-tui --json "my-server" tool list > api-docs.json

What happens: Always up-to-date documentation that reflects your server's real state.

📚 Documentation Hub

New to MCP-TUI?

• Quick Start Guide - 🚀 Connect to any MCP server in under 60 seconds
• User Guide - 🎮 Complete tutorials and real-world workflows
• Examples Showcase - 📊 See how others use MCP-TUI in production

Building with MCP-TUI?

• Developer Benefits - 💼 Why developers choose MCP-TUI for their workflow
• Development Guide - 🛠️ Complete development environment setup and productivity tips
• Architecture Guide - 🏗️ Technical design decisions and their benefits

Contributing Back?

• Contributing Guide - 🤝 How your contributions make a difference
• Troubleshooting Guide - 🔧 Solutions to common issues

Each guide is designed to get you productive quickly with clear benefits and practical examples.

🏗️ Why MCP-TUI is Built Right

The Architecture That Solves Real Problems:

MCP-TUI's architecture directly addresses the pain points developers face when working with MCP servers:

🛡️ Problem: MCP Servers Often Crash or Misbehave

Solution: Bulletproof Error Handling

• Graceful recovery from server crashes
• Clear error messages that help you fix issues quickly
• Built-in test servers that simulate real-world failures
• No cryptic JSON-RPC error codes - just plain English explanations

🌍 Problem: Different Servers Use Different Connection Methods

Solution: Universal Transport Layer

• Works with STDIO, HTTP, and SSE servers without configuration
• Automatic connection type detection
• Platform-specific optimizations for Windows, macOS, and Linux
• Handles process lifecycle management so you don't have to

📊 Problem: Hard to Test and Debug MCP Integrations

Solution: Developer-First Design

• Visual interface shows exactly what your server exposes
• CLI mode perfect for automated testing
• Structured logging reveals what's happening under the hood
• Modular architecture makes it easy to extend and customize

🚀 Problem: Slow Development Cycles

Solution: Instant Feedback Loop

• Connect to any server in one command
• Real-time tool execution with immediate results
• No need to write test clients or curl commands
• Clipboard integration for rapid iteration

💼 Business Value: Reduce MCP development time by 80%
🔧 Technical Benefit: Clean, testable, maintainable codebase
📈 Team Benefit: Consistent testing across all MCP servers

Want the technical details? Check out our Architecture Guide for in-depth design decisions.

🔧 Development

Development Prerequisites

What You Need:

• Go 1.21+ - For building and running MCP-TUI
• Node.js 14+ - For running the included test MCP servers
• Make - For simplified build commands

Why These Versions:

• Go 1.21+ provides the generics and performance features MCP-TUI relies on
• Node.js 14+ ensures compatibility with all modern MCP server implementations
• Make gives you simple commands like make test instead of complex go commands

Development Commands That Save Time

# 🎆 The Full Confidence Builder
make all           # Lint + test + build = ship with confidence

# 🚀 Quick Development
make dev           # Fast build with debug symbols for troubleshooting
make build         # Production build when you're ready

# 🧪 Bulletproof Testing
make test          # Fast unit tests for immediate feedback
make coverage      # See exactly what your tests cover
make test-servers  # Test against misbehaving servers (the real world)

# 📎 Quality Assurance
make lint          # Catch issues before code review
make release       # Multi-platform builds for distribution

Why These Commands Matter:

• make all ensures you never ship broken code
• make test-servers catches edge cases that break in production
• make coverage shows you exactly what needs more testing
• make dev gives you debug symbols for faster troubleshooting

Project Layout

The project follows Go standards and best practices:

• internal/ - Private application code, organized by domain
• cmd/ - Application entry points
• pkg/ - Public packages (currently none)
• Platform-specific code - Uses build tags (//go:build !windows)
• Interfaces first - Define contracts before implementations
• Structured errors - Custom error types with codes and context

🧪 Testing

Test Infrastructure

The project includes comprehensive testing:

• Unit tests - Individual component testing
• Integration tests - End-to-end MCP server interactions
• Error scenario testing - Problematic servers for edge cases

Test Servers

Intentionally problematic MCP servers for testing:

• invalid-json-server.js - Sends malformed JSON responses
• crash-server.js - Crashes at various points during communication
• timeout-server.js - Never responds or responds extremely slowly
• protocol-violator-server.js - Violates MCP protocol requirements
• oversized-server.js - Sends extremely large messages (MB-sized)
• out-of-order-server.js - Sends responses out of order or with wrong IDs

# Test all problematic servers
make test-servers

# Test specific failure scenario
./mcp-tui --cmd node --args "test-servers/crash-server.js" tool list

📋 Commands Reference

Command Line Arguments

Passing Multiple Arguments:

# Use multiple --args flags for multiple arguments
mcp-tui --cmd ./server --args arg1 --args arg2 --args arg3

# For arguments with spaces, quote each argument
mcp-tui --cmd ./server --args "arg with spaces" --args "another arg"

# Example with npm/npx
mcp-tui --cmd npx --args "@modelcontextprotocol/server-everything" --args "stdio"

# Real example with multiple flags
mcp-tui --cmd ./brum --args "--mcp" --args "--verbose"

Tool Operations

mcp-tui tool list                      # List all available tools
mcp-tui tool describe <name>           # Get detailed tool information
mcp-tui tool call <name> key=value     # Execute a tool with arguments

Resource Operations

mcp-tui resource list                  # List all available resources
mcp-tui resource read <uri>            # Read a resource by URI

Prompt Operations

mcp-tui prompt list                    # List all available prompts
mcp-tui prompt get <name> [args...]    # Get a prompt with arguments

Global Options

--url string         # URL for SSE servers (primary method)
--type string        # Transport type (currently: sse)
--timeout duration   # Connection timeout (default 30s)
--debug             # Enable debug mode with detailed logging
--log-level string  # Log level (debug, info, warn, error)
--json              # Output results in JSON format

# Legacy options (STDIO support coming back soon):
--cmd string         # Command to run MCP server (not yet implemented)
--args strings       # Arguments for server command (not yet implemented)

🔍 Error Handling & Debugging

Structured Error System

MCP-TUI uses a comprehensive error handling system:

// Error codes for different failure types
type ErrorCode string

const (
    ErrorCodeConnectionFailed     = "CONNECTION_FAILED"
    ErrorCodeServerCrash         = "SERVER_CRASH"
    ErrorCodeInvalidJSON         = "INVALID_JSON"
    ErrorCodeProtocolViolation   = "PROTOCOL_VIOLATION"
    // ... and many more
)

Debug Mode

Enable comprehensive debugging:

mcp-tui --debug --log-level debug --cmd your-server

This provides:

• Detailed connection logs - Transport-level communication
• Protocol message tracing - JSON-RPC message flow
• Error context and stack traces - Full error details
• Performance metrics - Timing and resource usage
• Component-specific logging - Structured logs by system component

⌨️ Keyboard Shortcuts

Global Shortcuts

• Ctrl+L - Open debug log panel from any screen
• Ctrl+C / q - Quit the application
• Tab / Shift+Tab - Navigate between UI elements
• Enter - Select/execute current item

Main Screen

• ↑↓ / j/k - Navigate through lists
• 1-9 - Quick select tools by number
• PgUp/PgDn - Page through long lists
• Home/End - Jump to start/end of list
• r - Refresh current tab
• Tab - Switch between tabs (Tools/Resources/Prompts/Events)

Tool Execution Screen

• Tab - Navigate between form fields
• Enter - Execute tool (when on button)
• Ctrl+V - Paste into current field
• Ctrl+C - Copy result to clipboard (after execution)
• b / Alt+← - Go back to tool list
• Esc - Cancel and go back

Debug Log Panel

• ↑↓ - Navigate log entries
• Enter - View detailed JSON for MCP messages
• c/y - Copy current log entry
• r - Refresh logs
• x - Clear all logs
• b / Alt+← - Return to previous screen

Clipboard Support

MCP-TUI supports clipboard operations for easy data transfer:

• Copy results: Press Ctrl+C after tool execution to copy the result
• Paste inputs: Press Ctrl+V in any input field to paste from clipboard
• Copy logs: Press c or y in the debug panel to copy log entries

Note: Text selection with mouse is not supported in the TUI. Use the built-in copy commands instead.

Common Error Scenarios

Connection Issues:

# Server command not found
Error: CONNECTION_FAILED: failed to start server process

# Server crashes during initialization
Error: SERVER_CRASH: server process exited unexpectedly (exit code: 1)

# Connection timeout
Error: CONNECTION_TIMEOUT: server did not respond within 30s

Protocol Issues:

# Server sends invalid JSON
Error: INVALID_JSON: failed to parse server response

# Missing required MCP fields
Error: PROTOCOL_VIOLATION: missing required field 'protocolVersion'

# Server not responding to requests
Error: SERVER_NOT_RESPONDING: no response to initialize request

Debugging JSON Unmarshaling Errors:

When servers send malformed responses, use --debug flag for detailed diagnostics:

# Example: Server sends array instead of object for properties field
mcp-tui --debug --url http://localhost:8080/mcp tool list

# Enhanced error output shows:
# - Original error message
# - Raw HTTP response body
# - Specific field causing the issue
# - Expected vs received types

🎯 Type System & Validation

Automatic Type Conversion

CLI arguments are automatically converted to proper JSON schema types:

# String values
mcp-tui tool call echo message="Hello World"

# Numeric values
mcp-tui tool call add a=5 b=3.14

# Boolean values
mcp-tui tool call configure enabled=true debug=false

# JSON objects/arrays
mcp-tui tool call process_data 'items=["a","b","c"]' 'config={"timeout":30}'

Schema Validation

• Input validation against tool schemas
• Type coercion with fallback to string
• Error reporting for invalid arguments
• Help generation from schema descriptions

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for:

• Development environment setup
• Coding standards and guidelines
• Testing requirements
• Pull request process
• Architecture decisions

Quick Start for Contributors

1. Fork and clone

   git clone https://github.com/your-username/mcp-tui.git
   cd mcp-tui
   

2. Set up development environment

   make deps
   make test
   

3. Make changes and test

   make all
   make test-servers
   

4. Follow coding standards

   • Use make lint for code quality
   • Add tests for new functionality
   • Update documentation for changes
   • Follow the established architecture patterns

🔧 Technical Details

Platform Support

• Unix/Linux - Full support with process groups and signal handling
• Windows - Job objects for process management
• macOS - Native signal and process handling

Dependencies

Core:

• github.com/mark3labs/mcp-go - MCP protocol implementation
• github.com/charmbracelet/bubbletea - TUI framework
• github.com/spf13/cobra - CLI framework

Development:

• golangci-lint - Comprehensive code linting
• Platform-specific build tools
• Integration test framework

Performance Characteristics

• Memory efficient - Streaming JSON processing
• Responsive UI - Async operations with progress tracking
• Resource cleanup - Proper process and connection management
• Concurrent safe - Thread-safe components with proper synchronization

📄 License

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

🙏 Acknowledgments

• Model Context Protocol specification
• Bubbletea TUI framework
• Cobra CLI framework
• mark3labs/mcp-go MCP implementation

📊 Project Status

• ✅ Core architecture - Clean, modular design implemented
• ✅ Error handling - Comprehensive error system with structured types
• ✅ Platform abstraction - Cross-platform process and signal management
• ✅ Test infrastructure - Problematic servers for edge case testing
• ✅ Development tooling - Makefile, linting, testing pipeline
• 🚧 CLI commands - Basic structure implemented, needs MCP integration
• 🚧 TUI implementation - Screen architecture in place, needs full UI
• 📋 Integration tests - Framework ready, tests planned
• 📋 Performance optimization - Profiling and optimization planned