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

# 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

{
  "mcpServers": {
    "vitest": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@djankies/vitest-mcp"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "vitest": {
      "command": "npx",
      "args": ["-y", "@djankies/vitest-mcp"]
    }
  }
}

{
  "mcpServers": {
    "vitest": {
      "command": "npx",
      "args": ["-y", "@djankies/vitest-mcp"],
      "type": "stdio"
    }
  }
}

{
  "mcpServers": {
    "vitest": {
      "command": "npx",
      "args": ["-y", "@djankies/vitest-mcp"]
    }
  }
}

{
  "mcpServers": {
    "vitest": {
      "command": "npx",
      "args": ["-y", "@djankies/vitest-mcp"]
    }
  }
}

{
  "mcpServers": {
    "vitest": {
      "command": "npx",
      "args": ["-y", "@djankies/vitest-mcp"]
    }
  }
}

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.

list_tests

List test files in your project. Helps keep LLMs from slipping back to using command line tools while working with tests.

run_tests

Execute tests with structured output.

Parameters:

analyze_coverage

Analyze test coverage with gap insights.

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:

1. vitest.mcp.config.ts - MCP-specific configuration (highest priority) 🔝
2. vitest.config.ts
3. vitest.config.js
4. vitest.config.mjs
5. vite.config.ts (if it contains test configuration)
6. vite.config.js (if it contains test configuration)
7. 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):

1. Command-line flags
2. Environment variables
3. Configuration file
4. 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.