Quick Start

Get your first MCP server test running in under 5 minutes.

Prerequisites

Node.js 18 or higher
An MCP server to test (or use our example)

Installation

Install MCP Jest globally for CLI usage:

npm install -g mcp-jest

Or add it to your project:

npm install --save-dev mcp-jest

Your First Test

1. Create a Simple MCP Server

First, let's create a basic MCP server to test. Save this as math-server.js:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({
  name: 'math-server',
  version: '1.0.0',
}, {
  capabilities: {
    tools: {},
  },
});

// Add a simple math tool
server.setRequestHandler('tools/list', async () => ({
  tools: [{
    name: 'add',
    description: 'Add two numbers',
    inputSchema: {
      type: 'object',
      properties: {
        a: { type: 'number' },
        b: { type: 'number' },
      },
      required: ['a', 'b'],
    },
  }],
}));

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'add') {
    const { a, b } = request.params.arguments;
    return {
      content: [{
        type: 'text',
        text: `The sum of ${a} and ${b} is ${a + b}`,
      }],
    };
  }
});

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

2. Write Your Test

Create a test file called math-server.test.json:

{
  "name": "Math Server Test Suite",
  "server": {
    "command": "node",
    "args": ["math-server.js"],
    "env": {
      "NODE_ENV": "test"
    }
  },
  "tests": [
    {
      "name": "Server should have correct metadata",
      "type": "capabilities",
      "expect": {
        "name": "math-server",
        "version": "1.0.0"
      }
    },
    {
      "name": "Should list the add tool",
      "type": "tools",
      "expect": {
        "tools": [
          {
            "name": "add",
            "description": "Add two numbers"
          }
        ]
      }
    },
    {
      "name": "Should add two numbers correctly",
      "type": "tool",
      "tool": "add",
      "arguments": {
        "a": 5,
        "b": 3
      },
      "expect": {
        "content": [
          {
            "type": "text",
            "text": "The sum of 5 and 3 is 8"
          }
        ]
      }
    }
  ]
}

3. Run Your Tests

$ mcp-jest math-server.test.json

🚀 MCP Test Runner
📋 Running: Math Server Test Suite

✓ Server should have correct metadata (45ms)
✓ Should list the add tool (12ms)
✓ Should add two numbers correctly (18ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Time:        0.523s

✨ All tests passed!

What's Next?

📦 Installation Guide

Detailed installation instructions and troubleshooting

🏗️ Test Structure

Learn about test configuration and organization

✅ Expectations

Deep dive into assertion patterns and matchers

💡 Pro Tip

Use the --watch flag during development to automatically re-run tests when your server code changes:

mcp-jest math-server.test.json --watch