MCP Test Client is a TypeScript testing utility for Model Context Protocol (MCP) servers.
11 stars
TypeScript
Updated Jul 24, 2025
Documentation
MCP Test Client
A testing utility for Model Context Protocol (MCP) servers. This client helps you test MCP server implementations by providing a simple interface for making tool calls and validating responses.
Features
- Easy-to-use testing interface for MCP servers
- Built-in support for tool listing and tool calls
- Type-safe implementation using TypeScript
- Assertion utilities for validating server responses
- Mock calculator server implementation for examples
Installation
bash
bun install mcp-test-clientUsage
Basic Example
typescript
import { MCPTestClient } from 'mcp-test-client';
describe('MCP Server Tests', () => {
let client: MCPTestClient;
beforeAll(async () => {
client = new MCPTestClient({
serverCommand: 'bun',
serverArgs: ['./path/to/your/server.ts'],
});
await client.init();
});
afterAll(async () => {
await client.cleanup();
});
test('should list available tools', async () => {
const tools = await client.listTools();
expect(tools).toContainEqual(
expect.objectContaining({
name: 'your-tool-name',
description: 'Your tool description',
})
);
});
test('should call a tool', async () => {
await client.assertToolCall(
'your-tool-name',
{ arg1: 'value1', arg2: 'value2' },
(result) => {
expect(result.content[0].text).toBe('expected result');
}
);
});
});Calculator Server Example
The package includes a mock calculator server for testing and learning purposes:
typescript
import { MCPTestClient } from 'mcp-test-client';
describe('Calculator Server Tests', () => {
let client: MCPTestClient;
beforeAll(async () => {
client = new MCPTestClient({
serverCommand: 'bun',
serverArgs: ['./tests/mocks/calculator.ts'],
});
await client.init();
});
afterAll(async () => {
await client.cleanup();
});
test('should perform addition', async () => {
await client.assertToolCall(
'calculate',
{ operation: 'add', a: 5, b: 3 },
(result) => {
expect(result.content[0].text).toBe('8');
}
);
});
});API Reference
MCPTestClient
Constructor
typescript
constructor(config: { serverCommand: string; serverArgs: string[] })Methods
init(): Promise- Initialize the client and connect to the serverlistTools(): Promise- Get a list of available tools from the servercallTool(toolName: string, args: Record): Promise- Call a specific toolassertToolCall(toolName: string, args: Record, assertion: (result: ToolResult) => void | Promise): Promise- Call a tool and run assertions on the resultcleanup(): Promise- Clean up resources and disconnect from the server
Development
Prerequisites
- Bun (v1.0.0 or higher)
Setup
1. Clone the repository
bash
git clone
cd mcp-test-client2. Install dependencies
bash
bun install3. Run tests
bash
bun testLicense
MIT
Contributing
1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request
Similar MCP
Based on tags & features
Trending MCP
Most active this week