Unit Test MCP

Standalone Model Context Protocol (MCP) server for AI-powered unit test generation, test execution, and coverage inspection.

Use this package when you want Unit Test MCP outside the VS Code extension, such as Copilot CLI, Claude Desktop, background agents, remote agent hosts, or custom MCP clients. In current VS Code builds, extension-provided MCP servers may be bridged into Copilot CLI or Claude agent sessions launched from VS Code. If the Unit Test MCP tools are already listed there, prefer the bridged extension server. Use this standalone server when the tools are missing, the client is not running under VS Code, or the remote agent host cannot see local VS Code extension MCP servers.

Features

• Multi-framework support: Jest, Vitest, Pytest, and .NET test projects.
• Test generation guidance: Framework-aware prompts for writing or improving unit tests.
• Coverage-aware workflows: Run tests with coverage, inspect existing reports, target uncovered lines or branches, and gate coverage by file, directory, or repo.
• Batch discovery: Find files that lack tests or have low coverage before generating tests one file at a time.
• Structured results: Test counts, failure messages, coverage percentages, target-met status, and machine-readable error codes.
• Standalone by default: Runs with npx; no VS Code extension required.

Requirements

| Requirement | Version | Notes | | --- | --- | --- | | Node.js | 20+ | Required to run the MCP server. | | Jest or Vitest | Project-defined | Only needed for JavaScript/TypeScript test runs. | | Python + pytest | Project-defined | Only needed for Pytest test runs. | | .NET SDK | 6.0+ recommended | Only needed for .NET test runs. |

Quick Start

Run the server directly with npx:

npx -y unittest-mcp

Most users should add it to an MCP client instead of launching it manually.

Add To Copilot CLI

In a Copilot CLI session, run /mcp add and fill in:

• Server Name: unittest-mcp
• Server Type: STDIO or Local
• Command: npx -y unittest-mcp
• Environment Variables: {}
• Tools: *

Or edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "unittest-mcp": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "unittest-mcp"],
      "env": {},
      "tools": ["*"]
    }
  }
}

Add To VS Code MCP Config

If you are not using the VS Code extension and want a workspace MCP config, add .vscode/mcp.json:

{
  "servers": {
    "unittest-mcp": {
      "command": "npx",
      "args": ["-y", "unittest-mcp"]
    }
  }
}

The VS Code extension is still the easiest path for VS Code users because it auto-registers the server, installs Copilot instructions, and provides the Unit Test MCP sidebar.

Add To Other MCP Clients

Use the same stdio command in any MCP-compatible client:

{
  "mcpServers": {
    "unittest-mcp": {
      "command": "npx",
      "args": ["-y", "unittest-mcp"]
    }
  }
}

Available Tools

| Tool | Purpose | | --- | --- | | generate_test | Get framework-aware guidance for creating or improving tests for one source file. | | generate_tests_batch | Scan a directory for files missing tests or needing coverage improvement. | | run_tests | Run Jest, Vitest, Pytest, .NET, or custom test commands, optionally with coverage. | | inspect_coverage | Read existing coverage artifacts without re-running tests. Supports Istanbul JSON, LCOV, Cobertura XML, OpenCover XML, and coverage.py JSON. | | find_test_files | Discover test files for a project or directory. |

Common Workflows

Generate Tests For One File

Ask your MCP client:

Generate unit tests for src/components/Button.tsx

The agent should call generate_test first, use the returned suggestedTestPath, and then write or update the test file.

Run Tests With Coverage

Run tests with coverage for src/components/Button.tsx

The agent should call run_tests with include_coverage=true. For a single file, scope='file' with an explicit test_pattern lets coverage.met reflect that file instead of the whole repo.

For folder workflows, use scope='directory' with scope_path:

{
  "root_dir": "C:/repo/my-project",
  "include_coverage": true,
  "scope": "directory",
  "scope_path": "src/services",
  "framework": "jest"
}

Directory scope aggregates per-file line and branch totals from Istanbul, LCOV, coverage.py JSON, Cobertura, or OpenCover artifacts. If the available artifact lacks per-file totals for the requested directory, coverage.met remains null and the response includes an explanatory note.

Inspect Existing Coverage

What lines are uncovered in src/components/Button.tsx?

The agent should call inspect_coverage with source_file. When following up on a specific previous run, it can pass coverage_dir or run_id returned by run_tests.

Find Test Gaps In A Folder

Find files in src/services that need tests

The agent should call generate_tests_batch, then process the returned files one at a time.

Tool Notes

• Prefer absolute root_dir values. For JavaScript/TypeScript, use the folder containing package.json; for Python, use the folder containing pytest config or the project root; for .NET, use the folder containing the solution or project file.
• Prefer explicit test file paths for test_pattern, such as src/foo.test.ts, tests/test_foo.py, or MyProject.Tests/MyClassTests.cs.
• Use scope_path with scope='directory' when the coverage target should apply to a source folder instead of the whole repo.
• run_tests filters noisy runner output by default while keeping failure details, stack traces, summaries, and coverage. Set compact_output=false when full raw output is needed.
• Coverage runs write to per-run directories under coverage/.unittest-mcp/<framework>/run-<id> so repeated or overlapping runs do not overwrite each other's reports.

Custom Commands

Set environment variables in your MCP client config when a project needs a custom runner command:

{
  "mcpServers": {
    "unittest-mcp": {
      "command": "npx",
      "args": ["-y", "unittest-mcp"],
      "env": {
        "UNITTEST_MCP_JEST_COMMAND": "pnpm jest",
        "UNITTEST_MCP_VITEST_COMMAND": "pnpm vitest",
        "UNITTEST_MCP_PYTEST_COMMAND": "uv run pytest",
        "UNITTEST_MCP_DOTNET_COMMAND": "dotnet test"
      }
    }
  }
}

Only set the variables you need.

Troubleshooting

The Client Does Not Show The Tools

• Confirm the MCP client is using stdio/local mode.
• Confirm the command is npx and the args are ["-y", "unittest-mcp"].
• Restart the MCP client session after editing its config.

Tests Do Not Run

• Jest/Vitest: ensure package.json exists at root_dir and the test framework is installed.
• Pytest: ensure Python, pytest, and any project dependencies are installed in the environment used by the MCP client.
• .NET: ensure the .NET SDK is on PATH and root_dir contains a .sln, .slnx, or .csproj.
• If process spawning fails, verify that node, npm, python, or dotnet are available to the MCP client, not only your interactive shell.

Coverage Is Missing

• Run tests with include_coverage=true, or call inspect_coverage only after coverage artifacts already exist.
• For targeted coverage work, pass source_file to inspect_coverage.
• For follow-up on a specific run, pass the coverageDir or runId returned by run_tests.

Structured Error Codes

Tool failures include a readable message plus structured error data when the MCP client supports it. Common codes include:

| Code | Meaning | | --- | --- | | INVALID_INPUT | A required argument is missing or malformed. | | INVALID_ROOT_DIR | root_dir is missing or is not a directory. | | INVALID_SCOPE | The requested coverage scope needs different arguments. | | NO_FRAMEWORK_DETECTED | Pass framework explicitly, such as jest, vitest, pytest, dotnet, or custom. | | TIMEOUT | Increase timeout_ms or investigate hanging tests. | | SPAWN_FAILED | The underlying runner could not be started. |

Telemetry

The standalone unittest-mcp npm package does not collect telemetry by default and does not bundle the Microsoft Application Insights SDK.

To opt in:

1. Install applicationinsights alongside unittest-mcp.
2. Set UNITTEST_MCP_TELEMETRY_CONNECTION_STRING before launching the server.

When either condition is missing, telemetry is disabled and the server continues normally. The VS Code extension version has separate extension telemetry.

Building Locally

From the repository root:

npm install
cd mcp-dist
npm install
npm run build

Run the built server directly:

node mcp-dist/dist/mcp-server.js

Create a local npm tarball:

cd mcp-dist
npm pack --dry-run
npm pack

Support

• Issues: https://github.com/gim-home/UnitTestMCP/issues
• Repository: https://github.com/gim-home/UnitTestMCP

License

MIT License. See LICENSE for details.