MCP-Jest is a testing framework for MCP servers. It provides Jest-like testing capabilities specifically for Model Context Protocol servers, enabling automated testing of how your agent tools, resources, and prompts interact with your MCP server. You can run tests against a locally started MCP server using the Node executor (node ./server.js) and specify which tools to exercise in your MCP implementation. The CLI and API both support tool-specific testing, snapshot testing, and integration with CI/CD workflows to ensure your MCP server remains compliant and reliable over time.

To use it, you typically start the MCP server and then run tests that target defined tools (for example, search or analyze) and verify the outputs against expectations. The library exposes a mcpTest function and a CLI interface (mcp-jest) that can invoke tests against a server process with a list of tools. This makes it easy to validate protocol compliance, test coverage, and behavior across updates.

Common workflows include auto-discovery of capabilities, protocol validation, and generating HTML reports for sharing results with teammates and stakeholders. You can integrate these tests into CI pipelines to catch regressions automatically when you modify your MCP server or its tools.

Prerequisites

• Node.js 18+ installed on your system
• A compatible MCP server implementation (the MCP server you want to test)

Install from source (recommended for contributing or local development)

1. Clone the repository git clone https://github.com/josharsh/mcp-jest.git
2. Navigate into the project cd mcp-jest
3. Install dependencies npm install
4. Run in development mode (build/test locally) npm run dev
5. Run tests npm test

Usage examples

• Run the server and test specific tools via code: npm install npm run dev

  Then using code exports

  node -e "async () => { const { mcpTest } = require('mcp-jest'); const results = await mcpTest({ command: 'node', args: ['./server.js'] }, { tools: ['search', 'email'] }); console.log(results); }()"
• Use the CLI to test a server: npx mcp-jest node ./server.js --tools search,email

Notes

• Ensure your MCP server is compatible with the MCP standard and can be invoked with a node server script (server.js).
• You can customize tests via a config file or programmatic API to cover connections, tools, resources, and prompts.

Tips and common issues:

• Node.js 18+ is required; upgrading Node if you encounter EPIPE or module resolution errors is advised.
• Use the CLI options to filter tests, set timeouts, and generate reports (e.g., --filter, --timeout, --reporter html).
• For CI integration, leverage the GitHub Actions example in the docs to automatically install dependencies and run tests on push or PRs.
• If tests fail due to MCP validation, ensure your server implements the necessary MCP endpoints and that capabilities are correctly auto-discovered.
• The tool supports multiple transports (stdio by default, with HTTP streaming and SSE support in broader scenarios).