🧪 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
• 🤝 Contributing
• 📜 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:

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: 22.12+ 🟢
• Vitest: 3.x, 4.x or 5.x installed in your project 🧪 (each major is tested in CI against real projects)
• Coverage: @vitest/coverage-v8 or @vitest/coverage-istanbul, same major version as Vitest (for coverage analysis) 📊

npm install --save-dev vitest @vitest/coverage-v8

The server always runs your project’s own Vitest (resolved from node_modules, including hoisted monorepo installs). It never downloads Vitest or runs commands through a shell.

🧰 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.

The tool runs every test that imports the target (vitest related), wherever your tests live (./test, __tests__, next to the source…), and reports coverage for the target only, including files that no test touches. Reports are written to a temporary directory, so your own coverage/ output is left alone. Test utilities, mocks, stories, and e2e files are excluded automatically.

🔄 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

If your project has a vitest.mcp.config.* file (.ts, .mts, .cts, .js, .mjs or .cjs), the MCP server passes it to Vitest with --config. Otherwise Vitest finds your normal vitest.config.* / vite.config.* as usual.

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, mergeConfig } from 'vitest/config';
import baseConfig from './vitest.config';

export default mergeConfig(baseConfig, defineConfig({
  test: {
    // MCP-specific settings, e.g. a longer timeout for AI-driven runs
    testTimeout: 30000,
  },
}));

Reporters, coverage output and console capture are set by the server on the command line, so you don’t need to configure them.

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 it in the project you set as root: npm install --save-dev vitest

“Coverage provider not found” / “does not match Vitest” - Install the provider matching your Vitest major, e.g. npm install --save-dev @vitest/coverage-v8@4 for Vitest 4 📊

Hook issues - Bypass with: BYPASS_VITEST_HOOK=1 npm test

Found a bug? Submit a bug report, please, and thank you.

🤝 Contributing

Releases are automated with semantic-release: merging to main publishes a new version when it contains fix: (patch), feat: (minor) or breaking (feat!:) commits, and updates the CHANGELOG. Please write commit messages in the Conventional Commits format; a commit hook and CI check them.

📜 License

MIT — See LICENSE.