Test Mcp

# 📦 test-mcp

<p align="center">
  <a href="https://www.npmjs.com/package/@loadmill/test-mcp"><img src="https://img.shields.io/npm/v/@loadmill/test-mcp?color=green" alt="npm version"></a>
  <a href="https://discord.gg/BHAVZUFrWX"><img src="https://img.shields.io/discord/1412375815236091906?logo=discord&label=discord" alt="Discord"></a>
</p>

<p align="center">
  <a href="#whats-test-mcp">What's test-mcp?</a> •
  <a href="#installation">Installation</a> •
  <a href="#getting-started">Getting Started</a> •
  <a href="#configuration--test-format">Configuration & Test Format</a> •
  <a href="#how-to-run">How to Run</a> •
  <a href="#cli-flags">CLI Flags</a> •
  <a href="#test-discovery">Test Discovery</a> •
  <a href="#interactive-mode">Interactive Mode</a> •
  <a href="#programmatic-api">Programmatic API</a> •
  <a href="#roadmap">Roadmap</a> •
  <a href="#contributing">Contributing</a> •
  <a href="#license">License</a>
</p>

---

**`test-mcp`** is a headless MCP client for automated testing of MCP servers and agents.

If you’re building an MCP server or agent, `test-mcp` lets you run natural-language test scripts and assertions end-to-end, so you can validate behavior in a fast and repeatable way.

https://github.com/user-attachments/assets/c4e5295b-7217-47f2-96d9-76befcea8b21

---

<h2 id="whats-test-mcp">💡 What's `test-mcp`?</h2>

`test-mcp` gives you three core components:

* **Configuration** – define your MCP servers and LLM provider in a single JSON file.
* **Test Files** – write flows of natural-language prompts and assertions in YAML.
* **Runner** – run tests from the CLI, get clear pass/fail results.

Together, these let you automate and validate MCP server behavior with simple, repeatable tests.

**Supported Transports & Providers:**
- **MCP Servers**: STDIO (local) and HTTP (remote)
- **LLM Providers**: Anthropic Claude and OpenAI GPT models
- **MCP Features**: Tools (done), Resources/Prompts/Sampling (planned)

---

<h2 id="installation">🏗️ Installation</h2>

```bash
# using npm
npm install -g @loadmill/test-mcp

# or with pnpm
pnpm add -g @loadmill/test-mcp
````

> [!NOTE]  
> While `test-mcp` itself can run on Node.js 18 or higher, many popular MCP servers require Node.js 20.  
> For the smoothest experience, we recommend using **Node.js 20**.

When running from source:

```bash
git clone https://github.com/loadmill/test-mcp
cd test-mcp
npm install
# For OpenAI (default example)
echo "OPENAI_API_KEY=your_api_key_here" > .env
# Or for Anthropic
echo "ANTHROPIC_API_KEY=your_api_key_here" > .env
npm run build
```

---

<h2 id="getting-started">🚀 Getting Started</h2>

To try `test-mcp` quickly with the included examples:

```bash
# from source
node build/index.js
```

This will run a demonstration that shows both local STDIO and remote HTTP MCP servers working together. The test rolls a local dice server and queries a remote MCP server registry.

---

<h2 id="configuration--test-format">📑 Configuration & Test Format</h2>

**1) Examp

... [View full README on GitHub]