Custom test matchers for Vitest and Jest to write automated test assertions for Model Context Protocol (MCP) tools.

Documentation

• Custom Matchers: Adds expect() matchers to assert on MCP interactions.
• MCP Client: Implements a special MCP client with extra features for testing and validation.

Currently the library supports:

• Testing MCP features: tools, resources, prompts.
• Testing stdin protocol servers.
• Integration with Vitest and Jest.

On the roadmap for future support:

• Planned: Testing HTTP services and Oauth.
• Planned: Testing for features: Discovery, Sampling, Roots, Elicitation.

If you're using a coding agent like Claude Code or Codex, you can use our builtin prompt to instruct the agent on how to use the library. Copy-paste this text as the prompt and it should do pretty well:

Run `npx -y expect-mcp@latest how-to-use` and follow the instructions to set up tests for this project.

Steps to install the library the normal way

npm install --save-dev expect-mcp

Or using other package managers:

# pnpm
pnpm add -D expect-mcp

# yarn
yarn add -D expect-mcp

Importing and using the library:

import { mcpShell } from 'expect-mcp';
import 'expect-mcp/vitest-setup'; // Install 'expect' matchers

it("the test", async () => {
  const app = mcpShell('path/to/mcp-server');
  await expect(app).toHaveTool('toolName');
  await expect(app).toHaveResource('config.json');

  const toolResult = await app.callTool('toolName', {});
  expect(toolResult); // ... check the result

  await app.close();
});

By default the library is ESM but we also include a CJS build. If your tests need to use CommonJS then import from expect-mcp/cjs. Example:

const { mcpShell } = require('expect-mcp/cjs');
require('expect-mcp/cjs/vitest-setup');

See the Documentation site for the full API and more examples.

• Node.js >= 20
• Vitest ^1.5.0 or Jest ^29.0.0

For bugs or feature requests, please use GitHub Issues!

MIT License - see the LICENSE file for details.

andyfischer

• Model Context Protocol - Learn more about MCP
• Vitest - Testing framework supported by this library
• Jest - Testing framework supported by this library