MCP Tester

This is not your grandpa's MCP Inspector. This is a real testing framework. No GUI, no clicking, no manual verification. Write tests, run them in CI, ship with confidence. 🚀

A production-ready MCP (Model Context Protocol) client for automated testing of MCP servers with Jest. No more manual clicking through inspectors — write real tests, run them in CI, break builds on regressions.

Capabilities

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        Your Test Suite                             │
│  ┌──────────┐  ┌───────────┐  ┌────────┐  ┌───────────────────┐  │
│  │   Jest    │  │  Vitest   │  │ assert │  │  Custom Runner   │  │
│  │ matchers │  │ matchers  │  │ module │  │  (any framework)  │  │
│  └────┬─────┘  └─────┬─────┘  └───┬────┘  └────────┬──────────┘  │
│       │              │             │                 │              │
│  ┌────▼──────────────▼─────────────▼─────────────────▼──────────┐    │
│  │                      MCPClient                              │    │
│  │  ┌──────────────────────────────────────────────────────┐  │    │
│  │  │  start() │ stop() │ listTools() │ callTool() │ ...   │  │    │
│  │  └──────────────────────┬───────────────────────────────────┘  │    │
│  │                         │                                      │    │
│  │  ┌──────────────────────▼───────────────────────────────┐    │    │
│  │  │         Retry │ Timeout │ Error Handling              │    │    │
│  │  │    MCPTimeoutError │ MCPConnectionError │ ...        │    │    │
│  │  └──────────────────────┬───────────────────────────────┘    │    │
│  └─────────────────────────┼─────────────────────────────────────┘    │
│                            │ stdio (JSON-RPC)                        │
│  ┌─────────────────────────▼─────────────────────────────────────┐  │
│  │              MCP Server (child process)                       │  │
│  │  ┌────────┐  ┌───────────┐  ┌──────────┐  ┌────────────┐   │  │
│  │  │ Tools  │  │ Resources │  │ Prompts  │  │ Sampling   │   │  │
│  │  └────────┘  └───────────┘  └──────────┘  └────────────┘   │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

Data flow: Your test calls MCPClient → which sends JSON-RPC over stdio → to the MCP server process → server responds → MCPClient returns typed results → your assertion validates them.

Key design: MCPClient manages the server lifecycle (spawn/kill) and protocol handling. Your tests never deal with the transport layer directly.

Why MCP Tester?

• Full protocol support — tools, resources, prompts, sampling, elicitation, notifications
• Built on the official SDK — @modelcontextprotocol/sdk v1.29.0
• Works out of the box — mock server included, 257 tests passing
• CLI included — test any server from the command line
• TypeScript first — strict types, ESM, full IntelliSense
• Parallel execution — fire multiple tool calls concurrently with Promise.all for blazing-fast test suites
• Retry with backoff — flaky servers? Configure retries so your CI stays green
• In-memory mock server — unit test your test logic without spawning real processes
• Custom Jest matchers — toHaveTool(), toHaveResource(), toHavePrompt() — and Vitest support

Test Coverage

Per-file coverage thresholds are set in jest.config.js to catch regressions while avoiding CI noise. Run npm run test:coverage to see the full breakdown by file. PRs automatically receive a coverage comment via GitHub Actions.

Install

npm install @slbdn/mcp-tester --save-dev

Requires Node.js >= 18. See Node.js Compatibility for details.

Quick Start

Connect and Use Tools

import { MCPClient } from '@slbdn/mcp-tester';

const client = new MCPClient({
  name: 'my-test-client',
  version: '1.0.0',
});

// Connect to your MCP server
await client.start({
  command: 'node',
  args: ['./your-mcp-server.js'],
});

// List and call tools
const tools = await client.listTools();
const result = await client.callTool({
  name: 'your-tool',
  arguments: { input: 'test' },
});

await client.stop();

Test with Jest

import { MCPClient } from '@slbdn/mcp-tester';

describe('My MCP Server', () => {
  let client: MCPClient;

  beforeEach(async () => {
    client = new MCPClient();
    await client.start({
      command: 'node',
      args: ['./my-server.js'],
    });
  });

  afterEach(async () => {
    if (client.isConnected()) {
      await client.stop();
    }
  });

  it('should list tools', async () => {
    const tools = await client.listTools();
    expect(tools.length).toBeGreaterThan(0);
  });

  it('should call a tool', async () => {
    const result = await client.callTool({
      name: 'my-tool',
      arguments: { input: 'test' },
    });
    expect(result.content).toBeDefined();
  });
});

Test from the Command Line

# Quick smoke test
npx @slbdn/mcp-tester test node ./server.js

# List tools (JSON output)
npx @slbdn/mcp-tester list-tools node ./server.js --json

# Call a tool
npx @slbdn/mcp-tester call-tool echo node ./server.js --params '{"message":"Hello"}'

# Short aliases: lt, ct, rr, gp
npx @slbdn/mcp-tester lt node ./server.js

See CLI Reference for all commands and options.

Speed Up Your Tests with Parallel Execution

MCP Tester is built for concurrency. Fire off multiple tool calls at once — no waiting in line:

import { MCPClient } from '@slbdn/mcp-tester';

const client = new MCPClient();
await client.start({ command: 'node', args: ['./server.js'] });

// 🔥 Run all calls in parallel — 5x faster than sequential
const [tools, resources, prompts] = await Promise.all([
  client.listTools(),
  client.listResources(),
  client.listPrompts(),
]);

// Parallel tool calls? No problem.
const [echo, sum, env] = await Promise.all([
  client.callTool({ name: 'echo', arguments: { message: 'hello' } }),
  client.callTool({ name: 'get-sum', arguments: { a: 1, b: 2 } }),
  client.callTool({ name: 'get-env', arguments: {} }),
]);

await client.stop();

Works because each MCP call is independent — the client multiplexes requests over a single stdio connection. No extra config needed. Just Promise.all and go.

Core API

See API Reference for full details including types, options, and error classes.

Custom Jest Matchers

Built-in matchers so your assertions read like English:

import {
  toHaveTool, toHaveResource, toHavePrompt,
  toReturnText, toReturnError, toReturnJson,
  setupJestMatchers,
} from '@slbdn/mcp-tester';

beforeAll(() => setupJestMatchers());

// Collection matchers
expect(tools).toHaveTool('echo');
expect(resources).toHaveResource('config://settings');
expect(prompts).toHavePrompt('greet');
expect(tools).toHaveToolCount(5);

// Tool result matchers
expect(result).toReturnText('Hello World');
expect(result).toReturnTextContaining('hello');
expect(result).toReturnError();
expect(result).toReturnJson({ status: 'ok' });
expect(result).toReturnContentCount(2);

Vitest Setup

import { setupVitestMatchers } from '@slbdn/mcp-tester';
import { beforeAll } from 'vitest';
// Add vitest.d.ts to your tsconfig for type safety
// /// <reference types="@slbdn/mcp-tester/vitest" />

beforeAll(() => setupVitestMatchers());

Works identically — same matchers, same { pass, message } format, just setupVitestMatchers() instead.

See Testing Guide for full testing patterns.

Assertion Utilities

Not using Jest? Running tests with a custom runTest() harness? The built-in assert module throws descriptive errors on failure — works with any runner:

import { MCPClient, assert } from '@slbdn/mcp-tester';

const client = new MCPClient();
await client.start({ command: 'node', args: ['./server.js'] });

await runTest("Get constant: c (speed of light)", async () => {
  const result = await client.callTool({
    name: "get_constant",
    arguments: { name: "c" },
  });
  assert.toolNumEquals(result, 299792458);
});

await runTest("Echo returns input", async () => {
  const result = await client.callTool({
    name: "echo",
    arguments: { message: "hello" },
  });
  assert.toolTextContains(result, "hello");
});

Documentation

Project Structure

mcp-tester/
├── src/
│   ├── client/MCPClient.ts      # Main client class
│   ├── cli/index.ts             # CLI tool
│   ├── assert.ts               # Assertion utilities
│   ├── matchers.ts             # Custom Jest matchers
│   ├── utils/
│   │   ├── errors.ts            # Error classes
│   │   ├── logger.ts            # Logging
│   │   └── env.ts               # Environment utilities
│   └── __tests__/               # 306 tests
│       ├── everything-server.test.ts  # Integration tests (server-everything)
│       ├── real-server.test.ts        # Integration tests (stdio transport)
│       ├── cli.test.ts                # CLI tool tests
│       └── fixtures/mock-server.ts    # In-memory mock server
├── examples/
│   ├── basic-test.ts            # Basic usage example
│   ├── full-test.ts             # Full capabilities example
│   ├── jest-matchers-example.ts # Jest matchers usage
│   ├── assert-example.ts        # Assert utilities usage
│   ├── everything-server-test.ts # Test against real MCP server
│   ├── stateful-server-test.ts  # Stateful server testing pattern
│   ├── mock-server.js           # Basic standalone MCP server
│   ├── simple-server.ts         # Minimal TypeScript MCP server
│   └── stateful-server.ts        # Stateful MCP server (counter + todos)
└── docs/                        # Documentation

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm run dev          # Watch mode — auto-rebuild on source changes
npm test             # Run tests (306 tests)
npm run lint         # Lint code
npm run format       # Format with Prettier

Troubleshooting

"Client not started" Error

Calling methods before start():

// ✗ Wrong
const client = new MCPClient();
const tools = await client.listTools(); // throws MCPNotStartedError

// ✓ Correct
const client = new MCPClient();
await client.start({ command: 'node', args: ['./server.js'] });
const tools = await client.listTools();

Timeout Errors

// Global timeout
const client = new MCPClient({ timeout: 60000 });

// Per-call override
await client.callTool({ name: 'slow-tool', arguments: {}, timeout: 30000 });

Server Won't Start

# Verify the server runs standalone first
node ./my-server.js

Check that the command and args are correct — MCPConnectionError includes the command and suggestions.

ESM Import Errors

// ✗ Wrong — missing .js extension
import { MCPClient } from './client/MCPClient';

// ✓ Correct
import { MCPClient } from './client/MCPClient.js';

Tests Fail in CI

• Set maxWorkers: 1 in Jest config (parallel workers can crash)
• Verify Node.js >= 18
• Check that server paths are correct

Debug Mode

const client = new MCPClient({ logLevel: 'debug', enableProtocolLogging: true });

All logs go to stderr — they won't interfere with test output.

New logging features:

• Timing: operations log elapsed time (e.g., Listed 4 tools in 12ms)
• Secret masking: API keys, tokens, and passwords are auto-masked (e.g., sk-ab...789)
• Pretty-printed JSON: protocol messages are formatted and masked
• Timestamps: enable with { timestamps: true }
• Colors: auto-enabled in terminals (cyan=debug, green=info, yellow=warn, red=error)

import { startTimer, prettyPrint } from '@slbdn/mcp-tester';

// Measure operation timing
const elapsed = startTimer();
await someOperation();
console.log(`Took ${elapsed()}ms`);

// Pretty-print objects with secret masking
prettyPrint({ apiKey: 'sk-proj-abc123...', count: 42 });

See Troubleshooting Guide for more details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make changes and test (npm run build && npm test)
4. Format and lint (npm run format && npm run lint)
5. Open a Pull Request

License

MIT — see LICENSE for details.