🧪 Vitest MCP Server
MCP Vitest runner with LLM-optimized test output, log capturing, and line-by-line coverage analysis.
Table of Contents
- 😢 The Problem with LLMs and Testing
- ✨ Key Features
- 🚀 Quick Start
- 📋 Requirements
- 🧰 Tools
- 🔄 Multi-Repository Support
- 🪝 Claude Code Hook
- 🤖 LLM instructions
- ⚙️ Configuration
- 🔍 Development Mode & Debugging
- 🔧 Troubleshooting
- 📜 License
😢 The Problem with LLMs and Testing 😢
- Noisy test output - Raw Vitest output can be extremely verbose eating up tokens/context with useless information.
- Full test suite runs - LLMs sometimes forget to limit the scope of the test run, causing full test suite runs to be executed.
- Buried console logs - Console logs can be hidden in test output, making it inefficient for LLMs to debug test failures.
- Raw coverage files - Raw coverage files are too large for AI to parse.
- Watch mode - LLMs get stuck when vitest runs in watch mode.
✨ Key Features ✨
- Smart Test Results with adaptive, structured output to limit noise.
- Console Log Capture to prevent logs from getting lost in test output.
- Coverage Analysis with line-by-line gap insights.
- Multi-Repository Support in a single session with context switching.
- Safety Guards prevent full project runs, watch mode, invalid vitest commands, and context hogging.
🚀 Quick Start 🚀
The Vitest MCP server can be used with any MCP-compatible IDE or tool and works with all Javascript or Typescript Vitests. The basic configuration is:
{
"mcpServers": {
"vitest": {
"command": "npx",
"args": ["-y", "@djankies/vitest-mcp"]
}
}
}
⚠️ Note: The above example may not be valid for all MCP clients. Verify your client's specific setup instructions.
🛠️ Client-Specific Setup
Select your preferred IDE or tool from the setup guides below:
Claude Code
Configuration Methods
Claude Code supports multiple configuration approaches:
Method 1: CLI Wizard (Interactive)
# Add server with interactive prompts
claude mcp add vitest -- npx -y @djankies/vitest-mcp
# Add to project scope (shareable with team)
claude mcp add --scope project vitest -- npx -y @djankies/vitest-mcp
Method 2: Direct Configuration File
Create or edit .mcp.json in your project root:
{
"mcpServers": {
"vitest": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@djankies/vitest-mcp"],
"env": {}
}
}
}
Configuration Scopes
- Local (default): Personal, project-specific - stored in user settings
- Project: Team-shared - stored in
.mcp.jsonin project root - User: Available across all projects - global configuration
Setup Steps
- Navigate to your project directory
- Choose either CLI or file-based configuration
- For CLI: Run
claude mcp add vitest npx -y @djankies/vitest-mcp - For file: Create
.mcp.jsonwith the configuration above - Verify with
/mcpcommand in Claude Code to see connection status
Usage
Once configured, use the MCP server naturally in your conversations:
- "Set the project root to this directory"
- "Run the auth component tests"
- "Show me the test coverage gaps"
Claude Desktop
Configuration Location
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Example Configuration
{
"mcpServers": {
"vitest": {
"command": "npx",
"args": ["-y", "@djankies/vitest-mcp"]
}
}
}
Setup Steps
- Open Claude Desktop
- Navigate to File → Settings → Developer
- Click Edit Config
- Add the configuration above
- Save and restart Claude Desktop
- Look for the MCP indicator (🔌) in the conversation input
VS Code
Configuration Methods
- Workspace:
.vscode/mcp.jsonin your project - Global: Run command
MCP: Open User Configuration
Example Configuration
{
"mcpServers": {
"vitest": {
"command": "npx",
"args": ["-y", "@djankies/vitest-mcp"],
"type": "stdio"
}
}
}
Setup Steps
- Install VS Code 1.86+ with GitHub Copilot
- Open Command Palette (
Cmd/Ctrl + Shift + P) - Run
MCP: Add Server - Select Workspace Settings or Global
- Add the configuration and save
- Access via Copilot Chat: Add Context → MCP Resources
Cursor
Configuration Location
- Project:
.cursor/mcp.jsonin your project directory - Global:
~/.cursor/mcp.jsonfor all workspaces
Example Configuration
{
"mcpServers": {
"vitest": {
"command": "npx",
"args": ["-y", "@djankies/vitest-mcp"]
}
}
}
Setup Steps
- Create the configuration file in your preferred location
- Add the server configuration
- Restart Cursor
- The MCP server will be available in Cursor's AI chat
- Use natural language to run tests: "Run the auth component tests"
Windsurf
Configuration Location
Similar to Cursor, but use serverUrl instead of url for remote servers
Example Configuration
{
"mcpServers": {
"vitest": {
"command": "npx",
"args": ["-y", "@djankies/vitest-mcp"]
}
}
}
Setup Steps
- Open Windsurf Settings (
Cmd/Ctrl + ,) - Navigate to Cascade settings
- Add MCP server configuration
- Reload MCP servers to activate
Cline (VS Code Extension)
Configuration via Cline UI
Example Configuration
{
"mcpServers": {
"vitest": {
"command": "npx",
"args": ["-y", "@djankies/vitest-mcp"]
}
}
}
Setup Steps
- Open VS Code with Cline extension installed
- Click the Cline icon in the sidebar
- Click MCP Servers → Configure MCP Servers
- Add the vitest-mcp configuration
- Save and reload VS Code
- Access through Cline's chat interface
3. Use It 🎮
Once configured, you can use natural language to interact with your tests:
- "Run the tests for this component"
- "Debug this test file"
- "Analyze the coverage for this file"
Or prepend your message with vitest-mcp: to ensure the tools are used:
- "vitest-mcp: run tests for this component"
- "vitest-mcp: debug this test file"
- "vitest-mcp: analyze coverage for this file"
📋 Requirements
- Node.js: 18+ 🟢
- Vitest: 0.34.0+ 🧪
- Coverage:
@vitest/coverage-v8(for coverage analysis) 📊
npm install --save-dev vitest@latest @vitest/coverage-v8@latest
🧰 Tools
set_project_root
🚨 Required first - Set the project root for all operations.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | Project root path |
list_tests
List test files in your project. Helps keep LLMs from slipping back to using command line tools while working with tests.
| Parameter | Type | Required | Description |
|---|---|---|---|
directory | string | Yes | Directory to search for test files |
run_tests
Execute tests with structured output.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
target | string | Yes | File or directory to test |
format | string | No | Output format: "summary" or "detailed" (auto-detects based on results) |
showLogs | boolean | No | Include console output with [stdout] or [stderr] prefixes |
project | string | No | Vitest project name for monorepos |
analyze_coverage
Analyze test coverage with gap insights.
| Parameter | Type | Required | Description |
|---|---|---|---|
target | string | Yes | File or directory to analyze coverage for |
format | string | No | Output format: "summary" (overview only) or "detailed" (includes line-by-line coverage) |
exclude | string[] | No | Patterns to exclude from coverage (e.g., ["**/.stories."]) |
Note: Coverage thresholds should be configured in your
vitest.config.tsfile, not via MCP parameters.
Automatically excludes test utilities, mocks, stories, and e2e files.
🔄 Multi-Repository Support
// Project A
set_project_root({ path: "/path/to/frontend" })
run_tests({ target: "./src" })
// Project B
set_project_root({ path: "/path/to/backend" })
run_tests({ target: "./src" })
🪝 Claude Code Hook
Automatically redirect Vitest commands to MCP tools:
# Run from project root
curl -o .claude/vitest-hook.sh https://raw.githubusercontent.com/djankies/vitest-mcp/refs/heads/main/.claude/vitest-hook.sh
chmod +x .claude/vitest-hook.sh
Then add to your project's .claude/settings.local.json:
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": ".claude/vitest-hook.sh" }]
}]
}
}
The hook can be bypassed with the BYPASS_VITEST_HOOK environment variable:
BYPASS_VITEST_HOOK=1 npm test
Or export for entire session:
export BYPASS_VITEST_HOOK=1
🤖 LLM instructions
Encourage claude or your ide to use the tools correctly: CLAUDE.example.md
⚙️ Configuration
Vitest Configuration Priority
The MCP server automatically detects and uses Vitest configuration files in the following priority order:
vitest.mcp.config.ts- MCP-specific configuration (highest priority) 🔝vitest.config.tsvitest.config.jsvitest.config.mjsvite.config.ts(if it contains test configuration)vite.config.js(if it contains test configuration)vite.config.mjs(if it contains test configuration)
This allows you to have a dedicated MCP-specific configuration that won't interfere with your regular development workflow:
// vitest.mcp.config.ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
// MCP-specific settings
reporters: ['json'],
coverage: {
enabled: true,
provider: 'v8',
reporter: ['json', 'html'],
},
},
});
Coverage Thresholds
To enable coverage threshold reporting in the analyze_coverage tool, just configure in your Vitest configuration file:
// vitest.config.ts or vitest.mcp.config.ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
thresholds: {
lines: 90,
functions: 85,
branches: 80,
statements: 90
}
}
}
});
💡 Note: Coverage analysis is always available regardless of threshold settings. Threshold reporting just helps keep your LLM on target.
Vitest-MCP Configuration File
Optional .vitest-mcp.json in home or project directory:
{
"safety": {
"allowedPaths": ["/Users/username/Projects"]
},
"testDefaults": {
"format": "detailed",
"timeout": 60000
}
}
Priority Order
Configuration is merged in the following order (highest priority first):
- Command-line flags
- Environment variables
- Configuration file
- Built-in defaults
🧑🏻💻 Development Mode & Debugging
Enable Debug Mode
Set the debug environment variable for detailed logging:
VITEST_MCP_DEBUG=true
Or in your MCP config file:
{
"mcpServers": {
"vitest": {
"command": "npx",
"args": ["-y", "@djankies/vitest-mcp"],
"env": {
"VITEST_MCP_DEBUG": "true"
}
}
}
}
Development Mode
Enable to test the server on its own codebase:
# Set in .env.development, or in your mcp config file
VITEST_MCP_DEV_MODE=true
🔧 Troubleshooting
"Vitest not found" - Install: npm install --save-dev vitest@latest
"Coverage provider not found" - Install: npm install --save-dev @vitest/coverage-v8@latest 📊
Hook issues - Bypass with: VITEST_HOOK_BYPASS=1 npm test
Found a bug? Submit a bug report, please, and thank you.
📜 License
MIT — See LICENSE.