Metadata-Version: 2.5
Name: mcptui
Version: 0.1.1
Summary: The Postman for MCP — Terminal UI & playground for Model Context Protocol
Author: kimarsen, mcptui contributors
License: MIT
License-File: LICENSE
Keywords: ai,anthropic,cursor,developer-tools,llm,mcp,model-context-protocol,postman,terminal,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=2.3.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pyperclip>=1.9.0
Requires-Dist: rich>=14.0.0
Requires-Dist: textual>=8.0.0
Requires-Dist: typer>=0.15.0
Description-Content-Type: text/markdown

# mcptui

<div align="center">

<h3><b>The Postman for Model Context Protocol (MCP)</b></h3>

*A modern, interactive Terminal UI and playground for testing, inspecting, and debugging MCP servers.*

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org)
[![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-8A2BE2.svg)](https://modelcontextprotocol.io)
[![Textual](https://img.shields.io/badge/Built%20With-Textual-green.svg)](https://textual.textualize.io)
[![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED.svg?logo=docker&logoColor=white)](https://github.com/kimarsen/mcptui/pkgs/container/mcptui)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/kimarsen/mcptui)

</div>

---

## 🚀 How to Run mcptui (Quickstart)

Choose whichever method you prefer:

### ⚡ Method 1: Zero-Install (Run directly via `uvx`)
If you have [`uv`](https://docs.astral.sh/uv/) installed, launch `mcptui` instantly without cloning or setting up virtual environments:
```bash
# Test drive the built-in demo server:
uvx --from git+https://github.com/kimarsen/mcptui mcptui demo

# Connect directly to your own server script:
uvx --from git+https://github.com/kimarsen/mcptui mcptui run "python my_server.py"
```

### 📦 Method 2: Clone & Run in PowerShell / Bash (Standard Method)
```powershell
# 1. Clone the repository
git clone https://github.com/kimarsen/mcptui.git
cd mcptui

# 2. Launch interactive demo in 1 command
uv run mcptui demo
```
*(If you don't have `uv` yet, install it via `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"` or use standard `pip install -e .`)*

### 🛠 Method 3: Install Globally as a CLI Tool
```bash
# With uv tool:
uv tool install --from git+https://github.com/kimarsen/mcptui mcptui

# Or with pipx:
pipx install git+https://github.com/kimarsen/mcptui.git

# Now 'mcptui' is available everywhere in your terminal:
mcptui demo
mcptui run "python my_server.py"
mcptui servers
```

### 🐳 Method 4: Run with Docker (GitHub Packages)
Run `mcptui` instantly without installing Python, uv, or dependencies on your system:
```bash
# Launch interactive demo in Docker:
docker run -it --rm ghcr.io/kimarsen/mcptui:latest demo

# Or connect to a remote MCP server via SSE:
docker run -it --rm ghcr.io/kimarsen/mcptui:latest connect http://host.docker.internal:8000/sse
```

### ☁️ Method 5: Run in Cloud with GitHub Codespaces
Open a preconfigured development environment directly in your browser with 1 click:  
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/kimarsen/mcptui)

### 📥 Method 6: GitHub Releases (.whl packages)
Pre-built wheels and source distributions are automatically packaged on every release. You can download them directly from the [Releases](https://github.com/kimarsen/mcptui/releases) page and install via `pip install mcptui-*.whl`.

---

## 🎯 Why mcptui?

Building and debugging **MCP (Model Context Protocol)** servers is rapidly becoming a core workflow for AI developers. But today, testing servers is painful:
- You have to edit `claude_desktop_config.json` and restart Claude Desktop repeatedly.
- You waste money and time on LLM token costs just to check if a simple function runs without syntax errors.
- Official web inspectors require Node.js, launch heavy browser tabs (`localhost:5173`), and don't fit into terminal workflows.

**`mcptui` fixes this completely.** It gives you a dedicated, keyboard-driven **Terminal UI (TUI)** playground to test tools, inspect schemas, browse resources, preview prompts, and watch live JSON-RPC 2.0 traffic in real time with zero token costs.

```
 ┌────────────────────────────────────────────────────────────────────────┐
 │ mcptui | Postman for MCP                [* mcptui-demo] (18ms)         │
 ├────────────────────────────────────────────────────────────────────────┤
 │ [1] Tools   [2] Resources   [3] Prompts   [4] Protocol Logs   [5] History │
 ├─────────────────────────┬──────────────────────────────────────────────┤
 │ Filter tools...         │ TOOL: calculate                              │
 │ ─────────────────────── │ Safe arithmetic calculation                  │
 │ > calculate             │                                              │
 │ > weather               │ Arguments (JSON)                             │
 │ > system_info           │ ┌──────────────────────────────────────────┐ │
 │ > text_analyzer         │ │ { "expression": "100 * 2 + 42" }         │ │
 │ > mock_query            │ └──────────────────────────────────────────┘ │
 │                         │ [Execute (Ctrl+Enter)] [Copy Result]  OK 18ms │
 │                         │                                              │
 │                         │ Response                                     │
 │                         │ ┌──────────────────────────────────────────┐ │
 │                         │ │ { "result": 242, "status": "success" }   │ │
 │                         │ └──────────────────────────────────────────┘ │
 └─────────────────────────┴──────────────────────────────────────────────┘
```

---

## 🛠 Building Your First MCP Server in 2 Minutes

Want to create your own MCP server and test it with `mcptui`? Here is the complete minimal guide:

### Step 1: Install the MCP Python SDK
```bash
pip install mcp
# or with uv:
uv add mcp
```

### Step 2: Write your server (`my_server.py`)
```python
import asyncio
from mcp.server.mcpserver import MCPServer

# 1. Initialize server
server = MCPServer("my-first-server")

# 2. Expose a tool that AI agents can execute
@server.tool(name="calculate_discount", description="Calculate price after applying percentage discount")
def calculate_discount(price: float, discount_percent: float) -> str:
    discounted = price * (1.0 - (discount_percent / 100.0))
    return f"Original: ${price}, Discount: {discount_percent}%, Final Price: ${round(discounted, 2)}"

# 3. Expose a static data resource
@server.resource(uri="store://catalog", name="Store Catalog", mime_type="application/json")
def get_catalog() -> str:
    return '{"items": ["Laptop", "Mouse", "Keyboard"], "status": "in_stock"}'

# 4. Run over standard input/output (stdio)
if __name__ == "__main__":
    asyncio.run(server.run_stdio_async())
```

### Step 3: Test and Debug Live in mcptui
```bash
uv run mcptui run "python my_server.py"
```
*Your new tool `calculate_discount` and resource `store://catalog` will instantly appear in the TUI! Fill in parameters, press `Ctrl+Enter`, and verify the output in 20ms.*

### Step 4: Connect to Claude Desktop or Cursor
Save it into your local `mcp.json` or `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "my-store-server": {
      "command": "python",
      "args": ["path/to/my_server.py"]
    }
  }
}
```
*(Or simply run `mcptui add my-store-server "python path/to/my_server.py"` and mcptui will register it for you!)*

---

## ✨ Features

- 🛠 **Interactive Tool Workspace**:
  - Auto-generates clean JSON parameter templates from tool `inputSchema`.
  - In-terminal JSON editor with error validation.
  - One-click execution (`Ctrl+Enter`) with live duration & latency measurement (`OK 18ms`).
  - Pretty-printed, syntax-highlighted output with clipboard copying.

- 📚 **Resource Explorer**:
  - Browse available server resources and dynamic URI templates.
  - Read resources with automatic syntax detection (Markdown, JSON, Plain Text).

- 💬 **Prompt Inspector**:
  - Test prompt templates with dynamic argument substitution.
  - Preview generated message sequences (System, User, Assistant) before sending them to LLMs.

- 🕵️ **Live JSON-RPC 2.0 Traffic Inspector**:
  - Intercepts and logs all raw protocol packets (`>>> SENT` and `<<< RECV`).
  - Search and filter messages by method (`tools/call`, `initialize`, etc.).
  - Protocol latency, request/response matching, and packet export.

- 🕒 **Execution History & Replay**:
  - Stores recent invocations with timestamps, status, input parameters, and duration.
  - Easily copy previous requests or inspect errors.

- 🔍 **Auto-Discovery & Local Server Management**:
  - Automatically scans and imports configurations from:
    - **Claude Desktop** (`claude_desktop_config.json` on macOS, Windows, Linux)
    - **Cursor** (`.cursor/mcp.json` & global settings)
    - Local project `mcp.json` / `.mcp.json`
  - Register any server permanently with `mcptui add <name> <command>`.
  - Switch between servers on the fly with `F2`.

---

## 🤖 Headless CLI & Automation

`mcptui` also works as a scriptable headless CLI for automated testing and CI/CD pipelines:

```bash
# Register a server into local mcp.json permanently
mcptui add notes "python examples/sample_server.py"

# List all registered and discovered servers
mcptui servers

# Headless capabilities inspection
mcptui list notes
# Or on the fly without saving:
mcptui list --cmd "python examples/sample_server.py"

# Execute a tool headlessly and get clean JSON output
mcptui call convert_temperature '{"value": 100, "from_scale": "C", "to_scale": "F"}' --server notes

# Remove a server from local config
mcptui remove notes
```

---

## ⌨️ Keybindings

| Key / Mouse | Action |
|-------------|--------|
| `1` – `5` | Switch active tab (Tools, Resources, Prompts, Logs, History) |
| `Ctrl + Enter` | Execute active tool / Read resource / Get prompt |
| `Double-Click` | Double-click resource title or list item to immediately READ resource |
| `F2` | Open Server Switcher modal |
| `F5` / `Ctrl + R` | Reload server capabilities |
| `Tab` / `Shift + Tab` | Navigate between sidebar, editor, and response view |
| `Ctrl + Q` / `q` | Quit mcptui |

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).  
Copyright (c) 2026 kimarsen and mcptui contributors.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies without restriction, subject to the conditions in the [LICENSE](LICENSE) file. Contributions, feedback, and stars are warmly welcome! ⭐
