Vitest MCP Server

A production-ready Model Context Protocol (MCP) server for running Vitest tests and analyzing coverage. This server provides AI assistants with intelligent tools for test-driven development workflows.

🚀 Features

Health Check Tool - Server connectivity verification
Test Execution Tool - Run Vitest tests with complete results
Coverage Analysis Tool - Detailed coverage reports with uncovered line analysis
Intelligent Resources - Access test results and coverage data as resources
Smart Caching - Automatic result caching for seamless data flow
Auto-Discovery - Automatically finds your Vitest configuration
Robust Execution - Fixed JSON parsing and execution reliability (v1.0.5)

🛠️ Usage

How it can be useful for local development

If your project uses Vitest, you can ask your AI agent in Cursor, Claude Desktop, or any other MCP-compatible editor these kinds of questions:

Run my unit tests. Check if there are any errors, and if so, fix them. Repeat this process until all unit tests pass.
Analyze the code coverage and identify the three most important files that have coverage below 80%. Then add the missing unit tests by examining the uncovered lines. Repeat this process until the coverage for these files exceeds 80% and all unit tests pass.

Integration with AI Assistants

Configure your AI assistant (like Claude Desktop, Cursor, etc.) to use this MCP server in the usual way. On top of that the server needs to know the path to your project root in order to be able to find your Vitest config file.

Why This MCP Server Needs Environment Variables

Unlike many other MCP servers, this one executes Vitest commands that must run in your specific project directory. Here's why:

Most MCP servers just analyze files, make API calls, or provide static information
This MCP server actually executes vitest run and vitest --coverage commands
Vitest requires its working directory to be your project root to find:
- vitest.config.ts/js
- package.json
- Test files
- Source files for coverage analysis
MCP servers run in their own process/directory, not your project directory
Without VITEST_PROJECT_DIR, Vitest can't find your config and fails

Optimized Configuration (Recommended)

For best performance and reliability, use only the environment variable (the cwd is redundant):

{
  "mcpServers": {
    "vitest-runner": {
      "command": "npx",
      "args": [
        "-y",
        "@madrus/vitest-mcp-server@latest"
      ],
      "env": {
        "VITEST_PROJECT_DIR": "/Users/<your-username>/path/to/your/project/root"
      }
    }
  }
}

Configuration Locations

Cursor (macOS/Linux):

File: ~/.cursor/mcp.json
Full path: /Users/<your-username>/.cursor/mcp.json

Claude Desktop (macOS):

File: ~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop (Windows):

File: %APPDATA%\Claude\claude_desktop_config.json

Example Complete Configuration

Here's a complete example for Cursor with multiple MCP servers:

{
  "mcpServers": {
    "vitest-runner": {
      "command": "npx",
      "args": [
        "-y",
        "@madrus/vitest-mcp-server@latest"
      ],
      "env": {
        "VITEST_PROJECT_DIR": "/Users/<your-username>/path/to/your/project/root"
      }
    }
  }
}

Important Setup Notes

Replace placeholders: Change /Users/<your-username>/path/to/your/project/root to your actual project path
Project root: The path should point to your project's root directory (where package.json and Vitest config files are located)
Restart required: After updating your MCP configuration, restart your AI assistant (Cursor, Claude Desktop, etc.)
Verify setup: Use the ping tool to verify the server is working correctly

Testing and Troubleshooting

Testing with MCP Inspector:

You can use the MCP Inspector to visually test the server's tools and resources before integrating with your AI assistant:

npx @modelcontextprotocol/inspector npx -y @madrus/vitest-mcp-server@latest

This opens a web interface where you can test the ping, run-vitest, and run-vitest-coverage tools interactively and view the available resources.

Common Issues and Solutions:

Server fails to start or times out:
- Check that your project path in VITEST_PROJECT_DIR is correct and absolute
- Verify the path exists and contains package.json
- Try running npx vitest run manually in your project directory
"Cannot find vitest config" errors:
- Ensure your project has a vitest.config.ts/js or vite.config.ts/js file
- Check that Vitest is installed in your project: npm list vitest
- Verify the config file is in the directory specified by VITEST_PROJECT_DIR

🔧 Available Tools

`ping`

Simple health check that returns "pong". Useful for verifying server connectivity.

Returns: "pong"

`run-vitest`

Executes Vitest tests and returns structured results.

Parameters:

projectDir (optional): Override auto-detected project directory

Features:

Auto-detects project directory by looking for vitest.config.ts
Returns JSON-formatted test results with detailed test information
Caches results for resource access
Handles test failures gracefully

Returns: Complete test execution results including:

Test suite summaries
Individual test results
Timing information
Pass/fail statistics

`run-vitest-coverage`

Executes Vitest tests with comprehensive coverage analysis.

Parameters:

projectDir (optional): Override auto-detected project directory

Features:

Fixed in v1.0.5: Now properly executes tests AND generates coverage
Comprehensive coverage analysis with file-by-file breakdown
Line-by-line uncovered code detection with line numbers
Smart formatting with status indicators (✅ Perfect, ⚠️ Partial, ❌ No coverage)
Coverage data caching for subsequent analysis
Handles large codebases efficiently

Returns: Test results + detailed coverage data including:

Per-file coverage percentages
Uncovered line ranges
Coverage status summaries
Branch and function coverage

📚 Available Resources

After running tests, the following resources become available:

`vitest://test-results`

Complete test execution results in JSON format.

`vitest://coverage-report`

Detailed coverage analysis with file-by-file metrics.

`vitest://test-summary`

Human-readable test summary with success percentages.

📊 Example Coverage Output

{
  "numTotalTests": 167,
  "numPassedTests": 167,
  "numFailedTests": 0,
  "coverage": {
    "app/components/AppBar.tsx": {
      "summary": {
        "lines": {"pct": 95.78, "total": 166, "covered": 159},
        "functions": {"pct": 33.33, "total": 3, "covered": 1},
        "statements": {"pct": 95.78, "total": 166, "covered": 159},
        "branches": {"pct": 84.21, "total": 19, "covered": 16}
      },
      "status": "⚠️ 7 lines uncovered",
      "uncoveredLines": "43-44, 49-50, 52, 63-64",
      "totalUncoveredLines": 7
    },
    "app/components/AuthErrorBoundary.tsx": {
      "summary": {
        "lines": {"pct": 100, "total": 64, "covered": 64},
        "functions": {"pct": 100, "total": 3, "covered": 3},
        "statements": {"pct": 100, "total": 64, "covered": 64},
        "branches": {"pct": 100, "total": 17, "covered": 17}
      },
      "status": "✅ Perfect coverage",
      "uncoveredLines": "none",
      "totalUncoveredLines": 0
    }
  }
}

🔧 Configuration

Project Detection

The server automatically detects your Vitest configuration by looking for:

vitest.config.ts
vitest.config.js
vitest.config.mjs
vite.config.ts
vite.config.js
vite.config.mjs

You can override the project directory using:

Tool parameter: projectDir
Environment variable: VITEST_PROJECT_DIR (recommended)
Auto-detection (default, may not work in all MCP setups)

Environment Variables

Variable	Description	Required	Default
`VITEST_PROJECT_DIR`	HIGHLY RECOMMENDED: Specifies your project directory since MCP servers run in isolated processes. Unlike other MCPs that just analyze files, this one executes Vitest commands that need to run in your project root.	No	Auto-detected
`NODE_ENV`	Set automatically to `test` during execution. You don't need to set this manually.	No	`test`

📈 Recent Improvements

v1.0.8 (Latest)

📦 Optimized npm package size: Reduced bundle size by ~60% (46.6kB → 19.2kB)
🧹 Excluded test files from production bundle: Tests no longer included in published package
⚡ Faster installs: Significantly reduced download size for npx usage
🔧 Fixed .npmignore format: Corrected file format and added comprehensive exclusions

v1.0.6-v1.0.7

📝 Updated documentation (this file)

v1.0.5

🔧 Fixed coverage tool execution: Now properly runs tests AND generates coverage
🔧 Fixed JSON parsing errors: Resolved malformed JSON output from coverage commands
📊 Enhanced coverage reporting: Better formatting and status indicators
🚀 Improved reliability: More robust error handling and timeouts

v1.0.4

🔧 Fixed test execution: Switched from programmatic API to spawn-based execution
📝 Better error reporting: More detailed error messages and debugging info

v1.0.3 and earlier

Basic test execution and coverage tools
Initial MCP server implementation

🏗️ Requirements

Node.js ≥ 22.0.0
Vitest ≥ 3.0.0
A Vitest configuration file in your project
AI assistant with MCP support (Cursor, Claude Desktop, etc.)

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🐛 Issues

If you encounter any issues, please report them on the GitHub Issues page.

🙏 Acknowledgments

Built with the Model Context Protocol SDK and designed for seamless integration with AI-powered development workflows.

@madrus/vitest-mcp-server

Vitest MCP Server

🚀 Features

🛠️ Usage

How it can be useful for local development

Integration with AI Assistants

Why This MCP Server Needs Environment Variables

Optimized Configuration (Recommended)

Configuration Locations

Example Complete Configuration

Important Setup Notes

Testing and Troubleshooting

🔧 Available Tools

ping

run-vitest

run-vitest-coverage

📚 Available Resources

vitest://test-results

vitest://coverage-report

vitest://test-summary

📊 Example Coverage Output

🔧 Configuration

Project Detection

Environment Variables

📈 Recent Improvements

v1.0.8 (Latest)

v1.0.6-v1.0.7

v1.0.5

v1.0.4

v1.0.3 and earlier

🏗️ Requirements

📄 License

🤝 Contributing

🐛 Issues

🙏 Acknowledgments

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators