MCP Server - TestDriver

Overview

The TestDriver MCP server exposes TestDriver’s computer-use tools — session_start, find, click, type, assert, check, screenshot, and more — over the Model Context Protocol. Any MCP-capable AI client can use it to drive a live sandbox and write real end-to-end tests. It runs as a local stdio process:

npx -p testdriverai testdriverai-mcp

and authenticates with your TD_API_KEY (from console.testdriver.ai/team).

Quick install (recommended)

testdriverai init wires up the MCP server, the agent, and the skills for you, writing each client’s config in the exact format and location it expects:

# interactive — pick your client(s)
npx testdriverai init

# one client
npx testdriverai init --client claude-code

# several
npx testdriverai init --client claude-code,cursor,vscode

# everything
npx testdriverai init --client all

init detects clients already present in your project and pre-selects them in the picker. Re-running init is safe — it merges the TestDriver entry into existing config without overwriting your other servers.

Client support matrix

Client	Auto-install	MCP config file	Config key
Claude Code	✅	`.mcp.json`	`mcpServers`
Claude Desktop	✅	OS-specific (see below)	`mcpServers`
Cursor	✅	`.cursor/mcp.json`	`mcpServers`
VS Code (Copilot)	✅	`.vscode/mcp.json`	`servers`
Windsurf	✅	`~/.codeium/windsurf/mcp_config.json`	`mcpServers`
Codex	✅	`~/.codex/config.toml`	`[mcp_servers]`
Zed	✅	`.zed/settings.json`	`context_servers`
Lovable	⚙️ partial	GitHub `AGENTS.md` + UI	—
Replit	⚙️ partial	`replit.md` + UI	—
v0 (Vercel)	📝 manual	web UI only	—

Each client uses a different top-level key for MCP servers. The most common mistake when configuring by hand is using mcpServers for VS Code (it wants servers), Codex (TOML [mcp_servers]), or Zed (context_servers).

Manual installation

If you’d rather configure by hand, use the snippets below. The stdio command is the same everywhere; only the wrapper key and file location change.

Add to .mcp.json at your project root (or ~/.claude.json for all projects):

{
  "mcpServers": {
    "testdriver": {
      "type": "stdio",
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "${TD_API_KEY}" }
    }
  }
}

Edit the Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "testdriver": {
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "your_api_key" }
    }
  }
}

Restart Claude Desktop after saving.

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "testdriver": {
      "type": "stdio",
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "${TD_API_KEY}" }
    }
  }
}

Add to .vscode/mcp.json. VS Code uses the servers key and an inputs prompt for secrets:

{
  "servers": {
    "testdriver": {
      "type": "stdio",
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "${input:testdriver-api-key}" }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "testdriver-api-key",
      "description": "TestDriver API Key From https://console.testdriver.ai/team",
      "password": true
    }
  ]
}

Windsurf reads MCP config globally. Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "testdriver": {
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "${TD_API_KEY}" }
    }
  }
}

Codex uses TOML. Add to ~/.codex/config.toml:

[mcp_servers.testdriver]
command = "npx"
args = ["-p", "testdriverai", "testdriverai-mcp"]
env = { TD_API_KEY = "${TD_API_KEY}" }

Zed calls them “context servers”. Add to .zed/settings.json (project) or ~/.config/zed/settings.json (global):

{
  "context_servers": {
    "testdriver": {
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": { "TD_API_KEY": "${TD_API_KEY}" }
    }
  }
}

Web-based clients

Lovable, Replit, and v0 run in the browser, so the MCP server can’t be launched as a local process. Configure them through each product’s UI.

Lovable

Connect your GitHub repo and run npx testdriverai init --client lovable — this writes AGENTS.md and the skills into the repo so Lovable’s agent picks them up.
In Lovable, open Settings → MCP and add the TestDriver server.

Replit

Run npx testdriverai init --client replit to write replit.md with the TestDriver agent guidance.
In Replit, open Tools → Integrations → MCP and add a custom MCP server.

v0 (Vercel)

v0 is fully UI-driven and does not read repo files.

Open v0.app/chat/settings/mcp-connections and add the TestDriver MCP connection.
Paste the agent guidance into Instructions (the + in the prompt bar).

Verifying the install

After installing, open your client’s chat and ask the agent to write a test:

@testdriver write a test that opens the homepage and asserts the title

If the MCP server is wired up correctly, the agent will start a session and you’ll see screenshots come back as it works. If tools don’t appear, check that TD_API_KEY is set and restart the client.

Agent — the test-creator that uses these tools
Skills — instruction files describing each tool
CI/CD — running the generated tests in your pipeline

​Overview

​Quick install (recommended)

​Client support matrix

​Manual installation

​Web-based clients

​Verifying the install

​Related

Overview

Quick install (recommended)

Client support matrix

Manual installation

Web-based clients

Verifying the install

Related