Vitest MCP Server

🧪 Vitest MCP Server

MCP Vitest runner with LLM-optimized test output, log capturing, and line-by-line coverage analysis.

😢 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:

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.json in 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.json with the configuration above
Verify with /mcp command 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"

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

Configuration Methods

Workspace: .vscode/mcp.json in 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

Configuration Location

Project: .cursor/mcp.json in your project directory
Global: ~/.cursor/mcp.json for 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"

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

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.ts file, 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.ts
vitest.config.js
vitest.config.mjs
vite.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.

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

Tools

AI-optimized Vitest interface that provides structured test output, visual debugging context, and intelligent coverage analysis for more effective AI assistance with testing.

Related MCP Servers

MCP Server
antfu
-
security
A
license
-
quality
A server that helps AI models better understand Vite/Nuxt applications, providing enhanced context awareness for development support.
Last updated -
760
MIT License
Vite MCP Server
ESnark
A
security
F
license
A
quality
Integrates Cursor AI with Vite Dev server, allowing AI agents to modify code and observe live updates through the Hot Module Replacement system in real-time.
Last updated -
11
46
20
MCP Frontend Testing Server
StudentOfJS
A
security
A
license
A
quality
Provides tools for frontend testing including code analysis, test generation, test execution, and React component testing for Jest and Cypress frameworks.
Last updated -
4
20
MIT License
VibeCheck
GroundNG
-
security
A
license
-
quality
AI-powered agent that integrates with coding assistants via MCP to automate web testing workflows, allowing developers to record tests, execute regression testing, and discover test flows using natural language prompts.
Last updated -
57
Apache 2.0

View all related MCP servers

Appeared in Searches

Information about Test-Driven Development (TDD)