<div align="center">

# `mcp-tap`

### Tap into any MCP server from your terminal — list tools, call them, inspect results, zero client setup required.

![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Language](https://img.shields.io/badge/language-python-green.svg) ![Status](https://img.shields.io/badge/status-active-success.svg) ![PyPI](https://img.shields.io/pypi/v/mcp-tap?style=flat-square&color=blue) ![License](https://img.shields.io/badge/license-MIT-green?style=flat-square) ![Python](https://img.shields.io/badge/python-3.10+-blue?style=flat-square&logo=python) ![MCP](https://img.shields.io/badge/MCP-2024--11--05-orange?style=flat-square)

<img src="demo.gif" alt="Demo" width="700" />

</div>

---

## 🎯 Why?

MCP servers are exploding in popularity (tradingview-mcp, OmniRoute, etc.) but developers have no quick way to test them from the CLI. The official MCP Inspector is a web UI that requires browser setup, and every other option means configuring a full AI client like Claude or Cursor just to verify a single tool call. mcp-tap fills this gap with a zero-config CLI that speaks the MCP JSON-RPC protocol directly over stdio.

**Target audience:** MCP server developers, AI agent builders, and DevOps engineers who need to quickly test, debug, and health-check MCP servers during development without launching a full AI client.

## ✨ Features

- ✨ **List all tools/resources/prompts exposed by any stdio-based MCP server**
- ✨ **Call any tool with JSON arguments and get formatted results instantly**
- ✨ **Ping/health-check an MCP server with latency measurement**
- ✨ **Rich terminal output with syntax-highlighted JSON and formatted tables**

## 🚀 Quick Start

```bash
# Install
pip install mcp-tap

# Run
mcp-tap --help
```

## 📦 Installation

### From Source

```bash
git clone https://github.com/YOUR_USERNAME/mcp-tap.git
cd mcp-tap
```

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v
```

## 🎬 Demo

The GIF above was recorded using [Charm VHS](https://github.com/charmbracelet/vhs):

```bash
vhs < demo.tape
```

## 📖 Usage

```bash
# Show help
mcp-tap --help

# Common usage examples
mcp-tap --example
```

## 🏗️ Architecture

```mermaid
graph LR
    A[Input] --> B[Core Engine]
    B --> C[Output]
    B --> D[Plugins]
    D --> E[Extensions]
```

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

MIT © 2026 — See [LICENSE](LICENSE) for details.

---

<div align="center">

**If this project helped you, please ⭐ star it!**

[Made with ❤️ and AI](https://github.com)

</div>