mcp-jest

Automated testing for Model Context Protocol (MCP) servers. Test your AI agent tools with Jest-like syntax, validate protocol compliance, and integrate with CI/CD.

🧪 Test tools, resources, and prompts — automated validation of your MCP server capabilities
📦 Zero config — works out-of-the-box with any MCP server (stdio, HTTP, SSE)
✅ Protocol validation — check MCP compliance with detailed scoring
🚀 CI/CD ready — GitHub Actions, Jenkins, CircleCI integration
📸 Snapshot testing — capture and compare outputs over time

MIT licensed · npm · GitHub

Install

npm install mcp-jest        # Project dependency
npm install -g mcp-jest     # Or globally for CLI

Use It

Test your MCP server in 30 seconds:

mcp-jest node ./server.js --tools search,email

Or use the JavaScript API:

import { mcpTest } from 'mcp-jest';

const results = await mcpTest(
  { command: 'node', args: ['./server.js'] },
  { tools: ['search', 'email'] }
);

console.log(`${results.passed}/${results.total} tests passed`);

What is MCP?

Model Context Protocol (MCP) is an open standard by Anthropic that lets AI assistants (Claude, ChatGPT, Gemini) connect to external tools, databases, and APIs. MCP-Jest tests those connections.

Why MCP-Jest?

You built an MCP server. But how do you know it works?

Manual testing is slow and error-prone
Silent failures break AI workflows
No native CI/CD integration for MCP
Debugging production failures is hard

MCP-Jest solves this with automated, repeatable testing.

Features

Core Testing

Automated Testing - Write tests once, run them everywhere
Comprehensive Coverage - Test connections, tools, resources, and prompts
Flexible Expectations - Simple strings or custom validation functions
CI/CD Ready - Works with GitHub Actions, Jenkins, CircleCI, etc.

Advanced Features

Snapshot Testing - Capture and compare MCP outputs over time
Test Filtering - Run specific tests with --filter and --skip
Watch Mode - Auto-rerun tests when files change
HTML Reports - Generate beautiful, shareable test reports

Transport Support

stdio - Default transport for local servers
HTTP Streaming - Test remote HTTP servers
SSE - Server-Sent Events support

Developer Tools

Auto-Discovery - Automatically discover and generate tests for all capabilities
Protocol Validator - Check MCP compliance with detailed scoring
GitHub Action - Native CI/CD integration

CLI Quick Reference

Command	Description
`mcp-jest node ./server.js --tools search`	Test specific tools
`mcp-jest --config test.json`	Use config file
`mcp-jest discover node ./server.js`	Auto-discover capabilities
`mcp-jest validate node ./server.js`	Check protocol compliance
`mcp-jest watch node ./server.js --tools search`	Watch mode

Common Options

Option	Description
`-t, --tools <tools>`	Comma-separated tools to test
`-c, --config <file>`	Config file path
`--timeout <ms>`	Test timeout (default: 30000)
`-u, --update-snapshots`	Update snapshot files
`--reporter html`	Generate HTML report

See CLI Reference for all options.

Example: CI/CD Integration

# .github/workflows/test.yml
- name: Test MCP Server
  run: |
    npm install -g mcp-jest
    mcp-jest node ./dist/server.js --tools "search,analyze"

Example: Config File

{
  "server": {
    "command": "node",
    "args": ["./server.js"]
  },
  "tests": {
    "tools": {
      "search": {
        "args": { "query": "test" },
        "expect": "content.length > 0"
      }
    },
    "timeout": 30000
  }
}

Documentation

Guide	Description
Getting Started	Step-by-step setup guide
CLI Reference	Complete CLI documentation
API Reference	Library API documentation
Examples	Real-world examples
Architecture	How MCP-Jest works
Troubleshooting	Common issues and solutions

Feature Guides

Requirements

Node.js 18+
MCP Server implementing Model Context Protocol

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

git clone https://github.com/josharsh/mcp-jest.git
cd mcp-jest
npm install
npm run dev
npm test

Security

See SECURITY.md for our security policy and vulnerability reporting.

Use Cases

MCP-Jest is ideal for:

MCP Server Developers - Test your tools, resources, and prompts before deployment
AI Application Teams - Ensure your MCP integrations work correctly
DevOps/SRE - Add MCP server testing to CI/CD pipelines
Open Source MCP Projects - Provide reliable testing for community contributions

Comparison with Other Tools

Feature	MCP-Jest	Manual Testing	Generic Test Frameworks
MCP Protocol Support	Native	Manual	Requires custom setup
Auto-Discovery	Yes	No	No
Snapshot Testing	Yes	No	Varies
Protocol Validation	Yes	No	No
CI/CD Integration	Built-in	Manual	Varies

Support

GitHub Issues - Bug reports and feature requests
GitHub Discussions - Questions and ideas
Model Context Protocol - Official MCP documentation

Related Technologies

Model Context Protocol (MCP) - The protocol standard
@modelcontextprotocol/sdk - Official MCP SDK
Claude - Anthropic's AI assistant with MCP support
Jest - JavaScript testing framework (inspiration for MCP-Jest)

License

MIT License - Use freely in commercial and open source projects.

Project Status

Built for the MCP ecosystem | Documentation | Examples | Contributing

Keywords: mcp testing, model context protocol testing, mcp server testing, ai agent testing, llm testing, claude mcp, chatgpt mcp, mcp tools testing, mcp validator, anthropic mcp, test mcp server, mcp ci cd, automated mcp testing

MCP Jest

README