mcp-testing-kit

What is mcp-testing-kit?

mcp-testing-kit is a lightweight TypeScript testing library that provides utilities to connect to an MCP server instance, send requests, receive notifications, and assert server behavior. It works with any testing framework (vitest, jest, etc.) and is designed for developers who need to test Model Context Protocol (MCP) servers.

How to use mcp-testing-kit?

Install as a dev dependency using npm i -D mcp-testing-kit. Import the connect and close functions, create an MCP server instance, call connect(server) to get a mock client, use the client methods (e.g., callTool, listTools) to interact with the server, and call close(server) to clean up after each test.

Features of mcp-testing-kit

• Works with any testing framework (vitest, jest, etc.)
• Lightweight, provides "just enough" utilities to test an MCP server
• Full TypeScript support
• Direct transport layer (no HTTP/SSE dependency)

Use cases of mcp-testing-kit

• Unit testing MCP server tools, resources, and prompts
• Verifying server responses to JSON-RPC requests
• Integration testing without setting up an actual network transport
• Automating server behavior assertions in CI pipelines

FAQ from mcp-testing-kit

What testing frameworks does mcp-testing-kit support?

It works with any testing framework, such as vitest, jest, and others.

Does it require running an actual MCP server over HTTP/SSE?

No. It creates a dummy transport layer that connects directly to the MCP server instance, bypassing HTTP/SSE.

What methods are available on the returned client?

The connect function returns a client with methods: listTools, callTool, listResources, listPrompts, getPrompt, onNotification, onError, onProgress, and sendToServer.

How do I clean up after a test?

Use the close(server) function to close the MCP server instance, typically in an afterEach hook.

Is mcp-testing-kit written in TypeScript?

Yes, it is built with TypeScript and provides type definitions.